Setup
Configure your identity providers when creating the theAuth instance.theauth.sso is null unless the sso key is passed, so use theauth.sso!. (or ?.) in your code. There is no SSO plugin: routes are served through theauth.sso.handleRequest.
- SAML 2.0
- OIDC
SSO connections
Connections link an org to an identity provider and route by email domain.Identity mapping
After a successful SAML or OIDC login, theAuth returns the identity from the IdP response:{ user: { id, email, name? }, orgId }. Email and name come from the SAML assertion or the OIDC email and name claims. An OIDC id_token without an email claim is rejected.
The user.id is derived deterministically, so the same IdP user always maps to the same ID: saml_ plus a SHA-256 hash of providerId:email for SAML, and oidc_ plus a SHA-256 hash of providerId:sub for OIDC.
SAML flow
POST /auth/sso/saml/:connectionId/acs) reads RelayState and does this for you. If you track AuthnRequest ids yourself, pass { expectedRequestId } instead (a plain string as the third argument still works).
Pending request ids and the assertion replay cache live in secondaryStorage (feature nonces). The default is process memory, which only works on a single instance. Behind a load balancer, configure a shared store such as Redis, Cloudflare KV or 'database'.
SAML security
Provider options
wantAuthnResponseSigned is deprecated. Setting it to false is a config error: signature verification cannot be turned off.
The sso config also takes storage (a SecondaryStorage, overrides the nonces store) and samlRequestTtlSeconds (default 600).
What is verified
- The response is base64 UTF-8 XML within the size, depth, attribute and element limits. DOCTYPE, ENTITY declarations, unknown entity references, duplicate attributes and unbound prefixes are rejected.
- The root is a
samlp:Responsewith exactly one top-levelAssertion. Encrypted assertions are rejected. - Signatures may sit only directly on the Response or on that Assertion, at most one each, and at least one must be present. Every signature present must verify.
- Each signature has exactly one
Referenceto a same-document#idthat resolves to exactly the element holding the signature. Any id value used twice anywhere in the document is rejected. - Transforms are exactly enveloped-signature followed by exclusive c14n (with or without comments, with an optional
InclusiveNamespaceslist). Canonicalization is exclusive c14n 1.0, computed on the parsed tree; the signature is removed structurally. The digest is compared in constant time. - Algorithms are allowlisted: RSA-SHA256 and SHA-256, plus RSA-SHA1 and SHA-1 only with
allowLegacySha1. Anything else is rejected. - Every claim (Issuer, NameID, attributes, Conditions, SubjectConfirmation, SessionIndex) is read by fixed child paths from the verified Assertion. Comments or child elements inside
NameID,Issuer,AudienceorAttributeValueare rejected. Statusis Success.DestinationmatchescallbackUrl(required when the Response is signed). Issuers matchidpEntityId.ConditionsNotBeforeandNotOnOrAfterhold within the skew, and everyAudienceRestrictionnames your entity id.- A bearer
SubjectConfirmationDatahas the rightRecipient, an unexpiredNotOnOrAfterand anInResponseToequal to the stored AuthnRequest id. - The assertion id has not been seen before. It stays in the replay cache until the assertion could no longer be accepted.
Threat model
The verifier assumes an attacker can post any XML to the ACS endpoint and can hold real signed responses for other users or other service providers of the same IdP. It is built to stop signature wrapping (claims from an unsigned element), references that do not resolve, comment truncation ofNameID, algorithm downgrade, replay of a captured response, responses meant for another SP, and unsolicited or cross-session responses. It trusts the configured cert and nothing in the message itself.
Not supported
- Encrypted assertions (
EncryptedAssertion,EncryptedID). - Detached signatures, signatures over the whole document (
URI=""), XPath or XSLT transforms, inclusive c14n, andObjectelements. - Signed AuthnRequests, the HTTP-Artifact binding and single logout.
- Certificate chain or expiry validation. Rotate keys by updating
cert. - More than one Assertion per Response.
OIDC flow
issuer/.well-known/openid-configuration. The id_token is verified using the IdP’s JWKS endpoint. getOidcAuthUrl also accepts a nonce as a third argument, and handleOidcCallback accepts expectedNonce as a third argument. Use theauth.sso.generateState() and validateState(state) to create and check short-lived state tokens (stateTtlSeconds, default 300).
Endpoints
Served bytheauth.sso.handleRequest(request). The handler does no authentication of its own, so put your own admin check in front of the connection routes.
Failed logins return
401 (or 429 when rate limited, by default 10 attempts per connection per 60 seconds, set with rateLimitMax and rateLimitWindowSeconds) with { error, code }. Pass onAuditEvent in the sso config to receive login success and failure events.
Related
Organizations
SSO connections are scoped to organizations.
SCIM
Automated user provisioning that pairs with SSO connections.
OIDC provider
Turn theAuth into an OIDC identity provider for downstream apps.
Admin
User management tools.