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 scopeTo 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
zorealclaim: the strength of the identity behind the login, as distinct fromacr, which grades the login event itself. - Client
- The relying-party client: one instance per registered ZOREAL client.
- Client
Builder - Builds a
Client. Start fromClient::builder. - IdToken
Claims - The claims of a verified ID token. The ID token never carries personal
data: email, names, birthdate and document fields come only from
/userinfo(seeUserinfo). - Login
- One verified login, returned by
Client::authenticate. - Private
Key - An ES256 signing key on P-256 for
private_key_jwt, with the optionalkidthe assertion header advertises when your registered JWKS names one. - TlsIdentity
- A TLS client certificate and its private key for
tls_client_auth. - Token
Response - The provider’s answer to a successful code exchange.
- Userinfo
- The claims
/userinforeturned: the personal data your client was granted (Tier B scopes). Every accessor returnsNonefor 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
acrclaim states it. Ordered weakest to strongest:Session < Device < Live, so a floor ofAcr::Deviceis satisfied by aAcr::Livetoken, never the reverse. - Client
Auth - How the client authenticates at
/token: the fourtoken_endpoint_auth_methodvalues a ZOREAL client can register. - Error
- Everything that can go wrong, in four kinds.
- KeyProtection
- The
key_protectionvalue of the assurance block. - Trust
Tier - The
trust_tiervalue of the assurance block. - Uniqueness
- The
uniquenessvalue of the assurance block.
Constants§
- ASSERTION_
LIFETIME - The lifetime of a
private_key_jwtclient assertion. The provider refuses an assertion whoseexpis 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
issinside the tokens. - DEFAULT_
LEEWAY - The default clock skew allowed on
exp,nbfandiat. 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
Loginis repeated from memory before the next call asks the provider again.
Traits§
- Expose
Secret - Expose a reference to an inner secret
Type Aliases§
- BoxError
- A boxed underlying error, kept as the
std::error::Error::sourceof anErrorso the transport or parse failure behind it stays inspectable. - Result
- The result type of this crate.
- Secret
String - Secret string type.