Expand description
§atlasauth
The official Rust backend verification crate for Atlas.
The Rust peer of @atlasauth/backend, atlas-go, and the Ruby SDK — same
verification semantics, same claim names, same @no-email.invalid handling.
It does two things a Rust server needs:
- Verify a session token locally against the instance JWKS — RS256, ES256, ES384, PS256 or EdDSA (the key type must fit the header algorithm),
with an explicit issuer,
exp/nbf/iatchecks, and an in-process JWKS cache keyed by URL that refetches on an unknownkidat most once a minute. No outbound call on the hot path. - Verify an end-user API key (
ak_…) against Atlas, with separate positive and negative caches so a busy API — or a caller hammering a bad key — does not hammer Atlas.
use atlasauth::AtlasBackend;
let backend = AtlasBackend::new(
"https://your-instance-fapi.atlasauth.net", // issuer
"https://your-instance-fapi.atlasauth.net/.well-known/jwks.json", // jwks_url
)?;
let claims = backend.verify(session_jwt()).await?;
if claims.has_permission("billing:read") {
// authorized
}This is a server-side crate: it uses your instance secret key (sk_…)
for API-key verification and must never ship to a browser or mobile app.
Structs§
- Access
Token Options - What an API requires of an access token.
- ApiKey
Cap - A per-key spend cap as the verify result reports it.
- ApiKey
CapUsage - A spend cap with its current-window usage, as the verify result reports it.
- ApiKey
Verification - The verify verdict. A failed verification is
valid = false, NOT an error; anApiKeyErrormeans the endpoint could not be reached or did not parse. - ApiKey
Verifier - Verifies end-user API keys against Atlas with separate positive/negative
caches. Construct with
ApiKeyVerifier::new(reqwest) orApiKeyVerifier::builder. - ApiKey
Verifier Builder - Builder for an
ApiKeyVerifier. - Atlas
Backend - Verifies Atlas session JWTs locally against the instance JWKS, with caching.
- Atlas
Backend Builder - Builder for an
AtlasBackend. Supply exactly one key source: ajwks_url(fetched + cached — the production default) or astatic_jwks(fully offline — the hermetic path for CI). - Atlas
Backend Options - Configuration for an
AtlasBackend. Build it withAtlasBackend::builder; the raw struct is public so options read clearly. - Backchannel
Logout Response - What to answer to Atlas’s back-channel logout POST:
200when the token verified (and your callback ended the sessions),503+Retry-Afterwhen Atlas should retry,400for a token that will never verify (Atlas never retries a400). - Claims
- A verified session’s claims. Construct one only via
crate::AtlasBackend::verify; a bareClaimscarries no proof. - Config
Error - A configuration error raised when building an
crate::AtlasBackendorcrate::ApiKeyVerifierwith an impossible combination of options. - Email
Address - A user’s email-address record, as the Backend API serializes it.
- Hmac
Dpop Nonce Source - DPoP nonces derived from a secret and the clock: a nonce is good for the window it was issued in and the next one, so every instance sharing the secret agrees without shared state.
- Http
Response - A raw HTTP response, as a
HttpPosttransport returns it. - Jwk
- One key in a JWKS document. Unknown members are ignored.
n/eare the base64url-encoded RSA modulus and exponent, passed verbatim tojsonwebtoken’sDecodingKey::from_rsa_components. - Jwks
- A JSON Web Key Set.
- Jwks
Cache - The in-process JWKS cache. Either serves a fixed
static_jwks(fully offline — the hermetic path a customer’s CI uses) or fetches fromurlthrough aJwksSource, caching with a TTL and a throttled kid-miss refetch. - Legacy
Issuer - One old issuer accepted during the cutover.
- Logout
Token Claims - The claims of a verified logout token. At least one of
sub/sidis set: end every local session forsidwhen present, otherwise every session ofsub. - Logout
Token Replay Cache - A small in-memory guard against a logout token being replayed: remember
each accepted
jtiuntil it can no longer verify, and refuse a repeat. - Memory
Dpop Replay Store - The in-process
DpopReplayStore: entries live until they expire, at mostmax_entriesof them. - Oidc
Organization - The organization a sign-in was made in.
- Oidc
Organization Membership - One membership from the
orgsclaim. - Oidc
SsoContext - The enterprise SSO context of a sign-in (the token’s
sso_*claims). - Parsed
Key - What
parse_key_prefixlearned from a credential’s prefix. - Reqwest
Transport - A reqwest-backed transport. Cheap to clone (the inner
reqwest::Clientis anArc). - Resource
Request - What verification reads from an HTTP request: the method and URL (absolute,
or a path resolved against
AccessTokenOptions::public_origin) for the DPoPhtu, and theAuthorizationandDPoPheader values. - Transport
Error - A transport-level failure while talking to a remote endpoint (JWKS fetch or the API-key verify endpoint). Carries a human-readable message only; it is never surfaced to an end user.
- TxnToken
Claims - The claims of a verified transaction token.
- TxnToken
Options - What to verify a transaction token against.
- User
- A user as the Backend API serializes it (
GET /v1/users/:id).private/unsafemetadata are never part of this surface. Unknown fields are kept inUser::extra.
Enums§
- Access
Token Result - The verdict of
AtlasBackend::verify_access_token. - ApiKey
Error - The result of an API-key verification call.
- Fetch
Outcome - The last JWKS-cache action, exposed so a caller (or a test) can assert the rate limit actually bit.
- KeyKind
- What a credential is, by its prefix.
- Verify
Error - Why a session-token verification failed. Coarse by design.
Constants§
- BACKCHANNEL_
LOGOUT_ EVENT - The
eventsmember a logout token must carry. - BACKCHANNEL_
RETRY_ AFTER_ SECONDS - Seconds to put in
Retry-Afterwhen the issuer’s keys could not be fetched. - CLOCK_
SKEW_ SECONDS - §7.3: five seconds either side, matching the server’s minting tolerance.
- DEFAULT_
BASE_ URL - The public API host. Override for self-hosted instances.
- DEFAULT_
MAX_ ENTRIES - Default max entries per cache (positive and negative each): 10 000.
- DEFAULT_
NEGATIVE_ TTL_ MS - Default negative-cache TTL: thirty seconds.
- DEFAULT_
POSITIVE_ TTL_ MS - Default positive-cache TTL: five minutes.
- DEFAULT_
TTL_ MS - §7.3 serves
Cache-Control: max-age=3600; honoured rather than ignored. - DPOP_
ALGS - The JWS algorithms accepted on a DPoP proof (and advertised in challenges and metadata). ES512 is not offered: the signature backend has no P-521.
- DPOP_
CLOCK_ SKEW_ SECONDS - Clock skew tolerated on a proof’s
iat. - DPOP_
PROOF_ MAX_ AGE_ SECONDS - How old a DPoP proof may be.
- LEGACY_
ISSUER_ ALGS - Better Auth’s
jwtplugin algorithms this crate can verify (the default forLegacyIssuer::algorithms). ES512 is the one Better Auth algorithm missing — see the module docs. - LEGACY_
SUBJECT_ CACHE_ MAX - Cap on cached subjects, so a stream of distinct tokens cannot grow memory without bound.
- LEGACY_
SUBJECT_ TTL_ MS - How long a resolved
sub→ Atlas id mapping is reused, in milliseconds. - LOGOUT_
TOKEN_ TYPE - The JWT
typheader a logout token carries. - NO_
EMAIL_ SENTINEL_ DOMAIN - The domain Atlas appends when a provider shares no email: the address is
shaped
"<provider>-<provider_user_id>@no-email.invalid". It is never a deliverable address and must never be shown to a user or used as an identity. - OIDC_
ORGANIZATION_ PARAM - The authorize parameter that pins the organization (id or slug) a sign-in is made in.
- OIDC_
SCOPE_ ORGANIZATIONS - The scope that adds the
orgsmembership list to the ID token and userinfo. - REFETCH_
INTERVAL_ MS - §7.3: at most one refetch per minute, however many kid-misses arrive.
- SIGNING_
ALGS - The JWS algorithms Atlas signs tokens with: an instance key is RS256 (the default), ES256, ES384, PS256 or
EdDSA. Every verifier in this crate is pinned to exactly this list:
noneand HMAC never verify, and the token’skidselects one published key whose type fixes which algorithm applies.
Traits§
- Dpop
Nonce Source - Hands out the server nonce a DPoP proof must carry (RFC 9449 §8) and checks
one.
currentgoes to the client in theDPoP-Nonceheader;validaccepts the nonces still in force. - Dpop
Replay Store - Guards against a DPoP proof being used twice. Back it with something every
instance of your API shares (Redis
SET key 1 NX PX ttl, a unique database key) when it runs on more than one;MemoryDpopReplayStoreprotects a single process. - Http
Post - Something that can POST a JSON body with a bearer token. Implemented by the
built-in reqwest transport (behind
reqwest-transport) and by any mock. - Jwks
Source - Something that can fetch (and parse) a JWKS from a URL. Implemented by the
built-in reqwest transport (behind the
reqwest-transportfeature) and by any custom/mock transport a caller supplies. - Subject
Resolver - Maps a legacy token’s
sub(the old provider’s user id) to the Atlas user id.Nonerefuses the token. Implemented for anyFn(&str, &Map<String, Value>) -> Option<String>throughLegacyIssuer::resolve_subject, and by [BackendSubjectResolver] (featurebackend), which looks the user up byexternal_id.
Functions§
- authenticated_
within - Whether
auth_time(epoch seconds) is withinmax_age_secondsofnow_ms. A missing or non-finiteauth_timeis never recent. - build_
challenge - An RFC 6750 / RFC 9449 / RFC 9728 challenge for
schemeBearerorDPoP(a DPoP challenge also lists the accepted proof algorithms). - build_
www_ authenticate - An RFC 6750 / RFC 9728 Bearer challenge. Without
errorit is the bare “authentication required” challenge (no token was sent). - dpop_
access_ token_ hash - The
atha DPoP proof carries fortoken: base64url(SHA-256(token)). - is_
access_ token - Whether
keyis a one-hour Atlas access token from an operator token exchange (atlas_live_at_…). - is_
partner_ link_ secret - Whether
keyis a partner-link secret (atlas_live_pl_…). - is_
platform_ key - Whether
keyis a platform key in either format (atlas_live_psk_…orpsk_…). - is_
publishable_ key - Whether
keyis a publishable key (pk_live_…/pk_test_…). - is_
secret_ key - Whether
keyis an instance secret key in either format (atlas_live_sk_…orsk_live_…). - is_
webhook_ secret - Whether
keyis a webhook signing secret in either format (atlas_live_whsec_…orwhsec_…). Webhook verification is unchanged: the whole string is the HMAC key. - jwk_
thumbprint - The RFC 7638 SHA-256 thumbprint (base64url) of a public EC, RSA or OKP JWK:
the
cnf.jkta DPoP-bound token carries.Nonefor an unsupported or incomplete key. - mfa_
org_ satisfied - Whether the session meets the active organization’s MFA policy: true when the
organization does not require MFA, or the token says
org_mfa_ok. The claims describe the ACTIVE organization only: passorg(its Atlas id or external id) to also require that the token’s active organization is that one. - mfa_
satisfied - The “requires MFA” rule: the server’s
mfa_satisfiedverdict when present, elsemfa == true, elseused_multi_factor, else an enterprise SSO sign-in. The same rule asClaims::mfa_satisfied, over loose values. - normalize_
htu - Reduce a URL to the form RFC 9449 §4.3 compares
htuin: scheme and host lower-cased, the default port dropped, an empty path as/, no query or fragment.Nonefor anything but an absolute http(s) URL. - oidc_
authorize_ url_ with_ organization - Add (or replace) the
organizationauthorize parameter: the sign-in must be made in that organization (a user who is not a member getsaccess_denied) and the token’sorg_*claims are that organization’s. - oidc_
organization_ of - The organization a sign-in was made in, or
Nonewhen none was involved. - oidc_
organizations_ of - Every membership (the
orgsclaim), orNonewhen theorganizationsscope was not requested. - oidc_
sso_ of - The enterprise SSO connection the user signed in through, or
None. - parse_
key_ prefix - Classify a credential by its prefix, accepting the suite format
(
atlas_live_sk_…) and the legacy one (sk_live_…,pk_test_…,psk_…,whsec_…).Nonefor anything else. - protected_
resource_ metadata - The RFC 9728 protected-resource metadata document for your API.
- protected_
resource_ metadata_ path - The RFC 9728 well-known path for a resource identifier (path-inserted form).
- protected_
resource_ metadata_ requiring_ dpop protected_resource_metadatathat also advertisesdpop_bound_access_tokens_required(pair it withrequire_dpop).- real_
email - Returns
Some(email)whenemailis a real address, orNonewhen it is empty or the@no-email.invalidplaceholder. The one function every other email helper funnels through. - system_
clock - The default clock: the real system time, in epoch milliseconds.
- used_
multi_ factor - Whether the claims prove a second factor:
acrisurn:atlas:acr:mfa, oramrincludesmfa. - verify_
transaction_ token - Verify
tokenagainst the issuer’s keys. Every failure is one coarse error string; nothing is revealed about which check failed.
Type Aliases§
- BoxFuture
- A boxed future, so the
JwksSourcetrait stays object-safe without pulling inasync-trait(keeps the dependency set minimal). - Clock
- A source of “now”, in epoch milliseconds.