Skip to main content

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.

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.
The SSO module does not create a user row, a membership, or a session. Your callback code receives the verified identity and decides what to do with it: create or look up your user, add them to the org, and issue a session. Do not treat the derived ID as an existing row in the users table.

SAML flow

The built-in ACS route (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

  1. 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.
  2. The root is a samlp:Response with exactly one top-level Assertion. Encrypted assertions are rejected.
  3. 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.
  4. Each signature has exactly one Reference to a same-document #id that resolves to exactly the element holding the signature. Any id value used twice anywhere in the document is rejected.
  5. Transforms are exactly enveloped-signature followed by exclusive c14n (with or without comments, with an optional InclusiveNamespaces list). Canonicalization is exclusive c14n 1.0, computed on the parsed tree; the signature is removed structurally. The digest is compared in constant time.
  6. Algorithms are allowlisted: RSA-SHA256 and SHA-256, plus RSA-SHA1 and SHA-1 only with allowLegacySha1. Anything else is rejected.
  7. 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, Audience or AttributeValue are rejected.
  8. Status is Success. Destination matches callbackUrl (required when the Response is signed). Issuers match idpEntityId.
  9. Conditions NotBefore and NotOnOrAfter hold within the skew, and every AudienceRestriction names your entity id.
  10. A bearer SubjectConfirmationData has the right Recipient, an unexpired NotOnOrAfter and an InResponseTo equal to the stored AuthnRequest id.
  11. 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 of NameID, 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, and Object elements.
  • 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.
The SAML verifier is our own code, written for Workers compatibility (Web Crypto only, no Node APIs). It is tested against xmllint and xml-crypto output, but it has not had an independent audit. If you need that assurance today, put an audited SAML library in front of theAuth and pass the resulting identity to your own session code.

OIDC flow

OIDC discovery is fetched automatically from 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 by theauth.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.

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.
Last modified on October 18, 2026