SAML 2.0 Single Sign-On

The Authentication Verifier can act as a SAML 2.0 Service Provider (SP): users of a realm sign in at the organisation's identity provider (IdP) — Microsoft Entra ID, Okta, ADFS, Keycloak, Shibboleth, … — and come back with the usual _ea_ session cookie. Nothing changes for the API servers that validate sessions: a SAML session is a session like any other, with as_as (auth scheme) set to "sa".

Table of Contents

• What is supported
• Architecture
• Prerequisites
• Step 1 — Create the SP signing key
• Step 2 — Configure the realm
• Step 3 — Register the realm at the IdP
• Step 4 — Sign users in from your application
• Login flow
• Identity mapping
• Security checks
• Certificate and key rotation
• Troubleshooting

What is supported

SAML is a login method for the users of a realm. It is never an administrator credential: admins keep signing in with the methods of the _ realm, which refuses SAML settings.

Architecture

flowchart LR
    subgraph user["End user"]
        B["Web browser"]
    end

    subgraph app["Your application"]
        APP["Web application<br/>(origin listed in allowed_return_origins)"]
        API["API server"]
    end

    subgraph idp["Identity provider"]
        IDP["SAML 2.0 IdP<br/>Entra ID, Okta, ADFS, Keycloak, Shibboleth"]
        DIR[("User directory<br/>AD, LDAP")]
        MFA["MFA factors"]
    end

    subgraph verifier["Authentication Verifier deployment"]
        EA["Authentication Verifier<br/>SAML 2.0 Service Provider<br/>/saml/{realm_id}/login, /acs, /metadata"]
        KEY["SP signing key and certificate<br/>(PEM files of saml_sp_params)"]
        DB[("Auth database<br/>SQLite, PostgreSQL, MySQL<br/>realms and saml_params")]
        SS[("Session store<br/>SQLite, PostgreSQL, MySQL, Redis<br/>sessions, pending SAML requests, replay cache")]
    end

    ADM["Realm administrator<br/>admin UI or admin API"]
    IDPADM["IdP administrator"]

    B -- "1. opens the application" --> APP
    B -- "2. login redirect and ACS form post" --> EA
    B -- "3. signs in" --> IDP
    IDP --> DIR
    IDP --> MFA
    B -- "4. API calls with the _ea_ cookie" --> API
    API -- "5. validates the session (/sessions)" --> EA
    EA --> DB
    EA --> SS
    KEY -.-> EA
    ADM -. "pastes IdP metadata, sets SAML realm settings" .-> EA
    EA -. "SP metadata" .-> IDPADM
    IDPADM -. "registers the SP" .-> IDP

The Authentication Verifier and the IdP never talk to each other directly: every SAML message travels through the browser (front channel), and trust is set up once, out of band, by exchanging metadata. The application and the API server only ever see the _ea_ session.

Prerequisites

1. A server built with the saml feature. SAML statically links the xmlsec and libxml2 C libraries, so it is off by default. Either use a prebuilt SAML build or build it yourself:

   • Prebuilt: the release publishes a SAML variant next to the standard one — packages whose file name ends in -saml (for example auth-verifier_<version>-1_amd64-saml.deb) and the Docker image ghcr.io/cosmian/auth-verifier-saml:<version>, a separate package from the standard ghcr.io/cosmian/auth-verifier. It is a static build only and installs under the same package name as the standard server, so install one or the other.
   • From source with Nix: nix-build -A auth-verifier-static-saml
   • From source with cargo, inside the Nix shell:

   nix-shell --run "cargo build --release --features auth_verifier/saml"
   

   A server built without the feature refuses realms carrying SAML settings (HTTP 400) and refuses to start if [saml_sp_params] is configured.

2. HTTPS. The ACS URL must be https://, and the login cookie that protects against login CSRF is Secure.

3. An SP signing key in the server configuration — Step 1. Without it the /saml routes don't exist and realms can't enable SAML.

Step 1 — Create the SP signing key

One RSA key signs the AuthnRequests of every SAML realm, and its certificate is published in the SP metadata that IdPs import. It is server configuration: it never goes through the database or the admin API.

openssl req -x509 -newkey rsa:3072 -sha256 -days 1095 -nodes \
    -subj "/CN=auth.example.com SAML SP" \
    -keyout saml-sp.key.pem -out saml-sp.cert.pem
chmod 600 saml-sp.key.pem

[saml_sp_params]
saml_rsa_private_key = "/etc/cosmian/saml-sp.key.pem"
saml_certificate     = "/etc/cosmian/saml-sp.cert.pem"

The server checks the pair at startup and stops if a file is unreadable, the key isn't RSA or is shorter than 2048 bits, or the certificate doesn't match the key. A self-signed certificate is fine: IdPs pin the certificate from the metadata rather than validating a chain. See Server configuration.

Step 2 — Configure the realm

In the admin UI, open the realm (Realms → Edit) and tick SAML 2.0 (single sign-on). The same settings can be sent through the API as auth_params.saml_params on POST /admins/realms or PUT /admins/realms/{realm_id}:

{
  "saml_params": {
    "metadata_xml": "<md:EntityDescriptor entityID=\"https://idp.example.com/…\">…</md:EntityDescriptor>",
    "sp_entity_id": "https://auth.example.com/saml/my-service",
    "sp_acs_url": "https://auth.example.com/saml/my-service/acs",
    "subject_attribute": "email",
    "normalize_subject_case": true,
    "role_attribute": "groups",
    "attribute_claim_map": { "department": "dept" },
    "allowed_return_origins": ["https://app.example.com"],
    "default_return_url": "https://app.example.com/"
  }
}

The IdP fields (idp_entity_id, idp_sso_url, idp_signing_certificates, idp_nameid_format) are derived by the server from metadata_xml on every save, and any values sent for them are ignored. The metadata is refused if it isn't a single SAML 2.0 EntityDescriptor, has expired (validUntil), has no HTTPS HTTP-Redirect SingleSignOnService, or has no signing certificate. Every refusal is an HTTP 400 naming the field (saml_params.<field>: <reason>); the admin UI shows it next to that field.

The admin UI previews the parsed metadata — IdP entity ID, sign-in URL, signing certificates with their expiry — before you save.

Step 3 — Register the realm at the IdP

The IdP administrator needs this server's SP details. Either give them the SP metadata:

https://auth.example.com/saml/my-service/metadata

(also available from the realm drawer's Download SP metadata button, or AuthClient::get_saml_metadata), or enter by hand:

Then paste the IdP's metadata into the realm (Step 2).

Step 4 — Sign users in from your application

Send the browser to the realm's login endpoint, with the page to come back to:

https://auth.example.com/saml/my-service/login?return_to=https://app.example.com/dashboard

After signing in at the IdP, the browser returns to return_to (or default_return_url) holding the _ea_ session cookie. return_to must be an https URL under one of allowed_return_origins; anything else is refused with HTTP 400 rather than silently replaced, so a misconfigured link is noticed.

Your API validates the session exactly as for any other method — see Session management.

Login flow

sequenceDiagram
    autonumber
    participant B as Browser
    participant EA as Authentication Verifier
    participant DB as Auth database
    participant RS as SAML request store
    participant SS as Session store
    participant IdP as Identity Provider
    participant APP as Application and API

    B->>EA: GET /saml/{realm_id}/login?return_to=URL
    note over EA: per-IP rate limit (same as /login)
    EA->>DB: get realm
    DB-->>EA: realm and saml_params
    note over EA: 400 if the realm does not use SAML<br/>return_to must be https under allowed_return_origins (else 400)<br/>absent return_to uses default_return_url
    EA->>RS: store pending request (request ID, realm, return URL, expires in 10 min)
    note over EA: AuthnRequest ID = request ID<br/>signed RSA-SHA256 with the SP key (HTTP-Redirect)
    EA-->>B: 302 Location: IdP SSO URL with SAMLRequest, RelayState = request ID, SigAlg, Signature<br/>Set-Cookie: _ea_saml = request ID (Secure, HttpOnly, SameSite=None, Path=/)

    rect rgba(128, 128, 128, 0.1)
        note over B,IdP: at the IdP, outside the Authentication Verifier
        B->>IdP: GET SSO URL
        note over IdP: checks the AuthnRequest signature<br/>authenticates the user (password, MFA)
        IdP-->>B: auto-submitting HTML form
    end

    B->>EA: POST /saml/{realm_id}/acs with SAMLResponse and RelayState<br/>Cookie: _ea_saml = request ID
    note over EA: _ea_saml cookie must equal RelayState (else 401)
    EA->>DB: get realm
    DB-->>EA: realm and saml_params
    EA->>RS: take pending request (RelayState, realm), single use
    RS-->>EA: pending request with return URL (none: 401)
    note over EA: base64-decode SAMLResponse<br/>verify signature against the IdP certificates (xmlsec)<br/>check algorithms, Issuer, InResponseTo, Audience,<br/>Recipient, Destination, validity window, AuthnStatement, Status
    EA->>RS: record assertion ID in this realm (replay cache)
    RS-->>EA: new (already seen: 401)
    note over EA: map identity: subject, roles, extra claims<br/>issue session token (as_as = sa, as_rid = realm)
    EA->>SS: upsert session
    EA-->>B: 200 HTML page continuing to the return URL<br/>Set-Cookie: _ea_ session (SameSite=Strict), _ea_saml cleared
    B->>APP: GET return URL with the _ea_ cookie
    APP->>EA: validate the session (/sessions)
    EA-->>APP: session data

The pending requests and the replay cache live in the session store's database (SQLite, PostgreSQL, MySQL or Redis) and are purged on the stale-session collector's interval. The /saml routes share the per-IP rate limit of /login.

On the SQL backends SAML opens its own connection pool with the session store's max_connections / min_connections, so plan for twice that many connections to that database. With auto_init_schema = false, create the two SAML tables yourself: saml_pending_request (request_id primary key, realm_id, return_url, created_at, expires_at) and saml_seen_assertion (primary key realm_id + assertion_id, or assertion_id_sha256 BINARY(32) on MySQL, and expires_at), each indexed on expires_at. The CREATE TABLE statements in server/src/saml/impls/ are the reference. Until they exist, SAML logins fail and the periodic cleanup logs errors.

The ACS answers with a small page instead of a redirect: the SameSite=Strict session cookie may be withheld on a navigation that directly follows the IdP's cross-site POST, and continuing from a page of this server makes it a same-site navigation.

SAML sessions don't go through this server's TOTP step: multi-factor authentication is the IdP's responsibility.

Identity mapping

Roles come straight from the IdP: this server does not filter them against its role list.

A SAML user is a different identity from a user of another scheme with the same name: a session's identity is the realm, the scheme (as_as) and sub together. Applications must key users on all three, never on sub alone.

Security checks

A response is accepted only if all of these hold; otherwise the ACS answers 401 SAML error: <reason> and logs an auth.login.failure event.

Certificate and key rotation

IdP signing certificate. When the IdP rolls its certificate, paste its new metadata into the realm. During a planned rollover, metadata listing both certificates keeps logins working across the switch. The admin UI shows each certificate's expiry in the preview and flags a realm card when a certificate expires within 30 days.

SP signing key. Replace the files named in [saml_sp_params] and restart the server, then have every IdP import the new metadata. IdPs that verify request signatures reject requests signed with the new key until they do.

Troubleshooting

Rejections are logged with the reason:

WARN event="auth.login.failure" realm=my-service auth_scheme="saml" SAML login rejected: …