Skip to main content

Crate zoreal_oauth2

Crate zoreal_oauth2 

Source
Expand description

Sign in with ZOREAL for Rust backends: the relying-party half of the OpenID Connect flow that the ZOREAL browser SDK (@zoreal/oauth2-react or @zoreal/oauth2-js) starts in the browser.

The browser SDK runs the pairing (QR code or app link) and hands your frontend an authorization code plus the code_verifier and nonce it generated. Your frontend posts all three to your backend, and this crate does the rest: the code exchange with your client authentication, ES256 verification of the ID token against the provider’s JWKS, and the /userinfo read for personal claims.

The crate is async (tokio and reqwest with rustls) and does not depend on any web framework.

§Example

use zoreal_oauth2::{Acr, Client, Error};

// Build once at startup and share; clones are cheap.
let zoreal = Client::builder(std::env::var("ZOREAL_CLIENT_ID").unwrap_or_default()) // ast_...
    .client_secret(std::env::var("ZOREAL_CLIENT_SECRET").unwrap_or_default())
    .build()?;

// In the handler your frontend posts { code, code_verifier, nonce } to:
let login = zoreal.authenticate(code, code_verifier, nonce, None).await?;

let sub = login.sub(); // pairwise, stable for your verified domain: the account key
let device_or_better = login.satisfies_acr(Acr::Device);
let email = login.email().await?; // from /userinfo, with the email scope

To require a fresh face capture, request acr_values: 'zoreal.live' in the browser SDK and pass Some(Acr::Live) as the floor here. Requesting is advisory; only the floor checked against the signed acr claim is a security control.

§Errors

Every fallible call returns Error, with four kinds: Error::Configuration, Error::Exchange, Error::Verification and Error::Userinfo. Nothing in this crate panics on input from the network or the browser, and no secret or token value appears in an error or in Debug output.

Structs§

Assurance
The ID token’s zoreal claim: the strength of the identity behind the login, as distinct from acr, which grades the login event itself.
Client
The relying-party client: one instance per registered ZOREAL client.
ClientBuilder
Builds a Client. Start from Client::builder.
IdTokenClaims
The claims of a verified ID token. The ID token never carries personal data: email, names, birthdate and document fields come only from /userinfo (see Userinfo).
Login
One verified login, returned by Client::authenticate.
PrivateKey
An ES256 signing key on P-256 for private_key_jwt, with the optional kid the assertion header advertises when your registered JWKS names one.
TlsIdentity
A TLS client certificate and its private key for tls_client_auth.
TokenResponse
The provider’s answer to a successful code exchange.
Userinfo
The claims /userinfo returned: the personal data your client was granted (Tier B scopes). Every accessor returns None for a claim that was not granted or that the holder’s document does not carry.

Enums§

Acr
How strongly a login was authenticated, as the signed acr claim states it. Ordered weakest to strongest: Session < Device < Live, so a floor of Acr::Device is satisfied by a Acr::Live token, never the reverse.
ClientAuth
How the client authenticates at /token: the four token_endpoint_auth_method values a ZOREAL client can register.
Error
Everything that can go wrong, in four kinds.
KeyProtection
The key_protection value of the assurance block.
TrustTier
The trust_tier value of the assurance block.
Uniqueness
The uniqueness value of the assurance block.

Constants§

ASSERTION_LIFETIME
The lifetime of a private_key_jwt client assertion. The provider refuses an assertion whose exp is more than 60 seconds out by its own clock; 50 seconds leaves room for the relying party’s clock to run ahead.
DEFAULT_CONNECT_TIMEOUT
The default bound on establishing a connection.
DEFAULT_ISSUER
The production ZOREAL OpenID Provider. Every endpoint is relative to the issuer, and the configured value must equal the iss inside the tokens.
DEFAULT_LEEWAY
The default clock skew allowed on exp, nbf and iat. The ID token lives two minutes, so verify it straight after the exchange.
DEFAULT_TIMEOUT
The default bound on every HTTP request.
JWKS_TTL
How long the fetched JWKS is held: the provider’s own ten-minute cache lifetime, so a busy relying party stays off the endpoint without holding a rotated-out key longer than the provider itself would.
USERINFO_RETRY_AFTER
How long a failed userinfo read on a Login is repeated from memory before the next call asks the provider again.

Traits§

ExposeSecret
Expose a reference to an inner secret

Type Aliases§

BoxError
A boxed underlying error, kept as the std::error::Error::source of an Error so the transport or parse failure behind it stays inspectable.
Result
The result type of this crate.
SecretString
Secret string type.