Skip to main content

zoreal_oauth2/
lib.rs

1//! Sign in with ZOREAL for Rust backends: the relying-party half of the
2//! OpenID Connect flow that the ZOREAL browser SDK
3//! ([`@zoreal/oauth2-react`](https://github.com/Bynn-Intelligence/zoreal-oauth2-react)
4//! or [`@zoreal/oauth2-js`](https://github.com/Bynn-Intelligence/zoreal-oauth2-js))
5//! starts in the browser.
6//!
7//! The browser SDK runs the pairing (QR code or app link) and hands your
8//! frontend an authorization `code` plus the `code_verifier` and `nonce` it
9//! generated. Your frontend posts all three to your backend, and this crate
10//! does the rest: the code exchange with your client authentication, ES256
11//! verification of the ID token against the provider's JWKS, and the
12//! `/userinfo` read for personal claims.
13//!
14//! The crate is async (tokio and reqwest with rustls) and does not depend on
15//! any web framework.
16//!
17//! # Example
18//!
19//! ```no_run
20//! use zoreal_oauth2::{Acr, Client, Error};
21//!
22//! # async fn handle(code: &str, code_verifier: &str, nonce: &str) -> Result<(), Error> {
23//! // Build once at startup and share; clones are cheap.
24//! let zoreal = Client::builder(std::env::var("ZOREAL_CLIENT_ID").unwrap_or_default()) // ast_...
25//!     .client_secret(std::env::var("ZOREAL_CLIENT_SECRET").unwrap_or_default())
26//!     .build()?;
27//!
28//! // In the handler your frontend posts { code, code_verifier, nonce } to:
29//! let login = zoreal.authenticate(code, code_verifier, nonce, None).await?;
30//!
31//! let sub = login.sub(); // pairwise, stable for your verified domain: the account key
32//! let device_or_better = login.satisfies_acr(Acr::Device);
33//! let email = login.email().await?; // from /userinfo, with the email scope
34//! # let _ = (sub, device_or_better, email);
35//! # Ok(())
36//! # }
37//! ```
38//!
39//! To require a fresh face capture, request `acr_values: 'zoreal.live'` in
40//! the browser SDK *and* pass `Some(Acr::Live)` as the floor here. Requesting
41//! is advisory; only the floor checked against the signed `acr` claim is a
42//! security control.
43//!
44//! # Errors
45//!
46//! Every fallible call returns [`Error`], with four kinds:
47//! [`Error::Configuration`], [`Error::Exchange`], [`Error::Verification`] and
48//! [`Error::Userinfo`]. Nothing in this crate panics on input from the
49//! network or the browser, and no secret or token value appears in an error
50//! or in Debug output.
51
52#![deny(missing_docs)]
53#![forbid(unsafe_code)]
54
55mod acr;
56mod auth;
57mod claims;
58mod client;
59mod error;
60mod jwks;
61mod jwt;
62mod login;
63
64use std::time::Duration;
65
66pub use acr::Acr;
67pub use auth::{ClientAuth, PrivateKey, TlsIdentity};
68pub use claims::{Assurance, IdTokenClaims, KeyProtection, TrustTier, Uniqueness, Userinfo};
69pub use client::{Client, ClientBuilder, TokenResponse};
70pub use error::{BoxError, Error, Result};
71pub use login::Login;
72pub use secrecy::{ExposeSecret, SecretString};
73
74/// The production ZOREAL OpenID Provider. Every endpoint is relative to the
75/// issuer, and the configured value must equal the `iss` inside the tokens.
76pub const DEFAULT_ISSUER: &str = "https://id.zoreal.com";
77
78/// How long the fetched JWKS is held: the provider's own ten-minute cache
79/// lifetime, so a busy relying party stays off the endpoint without holding a
80/// rotated-out key longer than the provider itself would.
81pub const JWKS_TTL: Duration = Duration::from_secs(600);
82
83/// The default bound on every HTTP request.
84pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(10);
85
86/// The default bound on establishing a connection.
87pub const DEFAULT_CONNECT_TIMEOUT: Duration = Duration::from_secs(3);
88
89/// The default clock skew allowed on `exp`, `nbf` and `iat`. The ID token
90/// lives two minutes, so verify it straight after the exchange.
91pub const DEFAULT_LEEWAY: Duration = Duration::from_secs(30);
92
93/// The lifetime of a `private_key_jwt` client assertion. The provider refuses
94/// an assertion whose `exp` is more than 60 seconds out by its own clock;
95/// 50 seconds leaves room for the relying party's clock to run ahead.
96pub const ASSERTION_LIFETIME: Duration = Duration::from_secs(50);
97
98/// How long a failed userinfo read on a [`Login`] is repeated from memory
99/// before the next call asks the provider again.
100pub const USERINFO_RETRY_AFTER: Duration = Duration::from_secs(2);