Skip to main content

Overview

protocol: saml makes the gateway a SAML 2.0 service provider instead of an OIDC client. Sessions, user paths, group mapping, sign-out, and sign-in events work exactly as described for OIDC SSO; only the way a login is proved changes.
  • One protocol, one identity provider per gateway. With protocol: saml, the OIDC client settings (issuer_url, client_id, client_secret, redirect_url) must be unset, in YAML and in the environment. With protocol: oidc, every saml setting must be unset. Startup stops otherwise.
  • Switching protocol changes every principal ID. The ID stored in request log entries is derived from the protocol, the identity provider, and the subject, so the same person appears under a new principal after the switch.
SAML needs the saml entitlement in addition to sso. Like every enabled SSO configuration it fails closed: startup aborts when either entitlement is missing or the configuration is invalid. The gateway never falls back to OIDC or to an unprotected Dashboard.

Configure SAML

The same setup with environment variables, which override the YAML values:
The shared settings in Identity and admission keep their meaning.

Register the gateway

The gateway publishes two URLs, both below any BASE_PATH:
1

Create a SAML 2.0 application at the identity provider

Import the service provider metadata URL if the provider supports it and the gateway is already running. Otherwise enter the ACS URL with the HTTP-POST binding and the entity ID (audience) by hand.
2

Sign the assertion

The assertion itself must be signed with RSA-SHA256 or stronger and an RSA key of at least 2048 bits. Signing only the response is not enough. Do not encrypt the assertion. The gateway sends unsigned requests over HTTP-Redirect.
3

Send a stable subject and the attributes you use

Use a persistent NameID, or send an immutable user ID as an attribute and name it in principal_attribute. Release the attribute for the user path and, if you use admin_groups or group mappings, the groups attribute with only the groups the gateway needs.
4

Give the gateway the identity provider metadata

Set idp_metadata_url, or download the metadata and set idp_metadata_file. The metadata must describe one identity provider with an HTTP-Redirect sign-on endpoint and at least one signing certificate.
5

Start the gateway and sign in

Open /sso/login below any BASE_PATH. If the login fails, look up the reason in Rejected login reasons.
These steps use generic SAML 2.0 terms; setting names differ between identity providers. SAML sign-in has so far been verified against a test identity provider only, so treat a first rollout with your provider as an integration to test, not a known-good recipe.

Attributes and the principal

user_path_claim and groups_claim name SAML attributes, either directly by the attribute Name or through an alias in saml.attributes:
  • An alias hides a SAML attribute of the same name.
  • The user path attribute must have exactly one value; it is trimmed. Group values are not trimmed and are compared exactly as sent. A groups attribute with a single empty value counts as no groups, and one with a non-text value refuses the login with claim_mapping_failed while admin_groups or group mappings are set.
  • An assertion without the groups attribute that carries Entra ID’s http://schemas.microsoft.com/claims/groups.link instead (sent for people in more than 150 groups) is refused with groups_overage while admin_groups or group mappings are set. See Limits.
  • Changing protocol, or the attribute that user_path_claim or groups_claim resolves to through saml.attributes, ends existing sessions, as described in When the configuration changes.
  • allowed_domains and the default user_path_claim: email read the attribute named or aliased email. The user path is lower-cased only with user_path_claim: email or user_path_case_insensitive: true.
  • The principal is the NameID, or principal_attribute when set. A transient NameID changes at every login and is refused unless principal_attribute is set.

Email trust

trust_email decides whether the email attribute counts as a verified email. It defaults to false because SAML has no equivalent of OIDC’s email_verified: a signature proves the identity provider sent the address, not that it checked it. The user path is also the session’s access scope, so if people can edit their own email at the identity provider, one person could set a colleague’s address and sign in on that colleague’s path. Without trust_email, startup refuses a configuration that depends on the email:
  • user_path_claim that reads it, which includes the default user_path_claim: email;
  • allowed_domains;
  • groups_claim that reads it, when admin_groups or group mappings are set.
So choose one of the following:
The startup check only recognises names: email, the attribute aliased as email, and the well-known email attributes http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.xmlsoap.org/claims/EmailAddress, mail, email, EmailAddress, User.Email, urn:oid:0.9.2342.19200300.100.1.3, and urn:oid:1.2.840.113549.1.9.1, all compared case-insensitively, directly or through an alias. An attribute that carries an email, or any other value people can edit, under another name passes. Never use an attribute a user can edit for user_path_claim or groups_claim.

What is checked on every response

A login succeeds only when all of the following hold. Each failure has its own rejection reason.
  • It answers a login this browser started. The signed transaction cookie (valid for 10 minutes), RelayState, and InResponseTo must match.
  • It is addressed to this gateway. Destination and Recipient equal acs_url, and the audience is the gateway’s entity ID.
  • It comes from the configured identity provider. The issuer is the entity ID in the metadata.
  • The assertion itself is signed by a currently valid signing certificate from the metadata, with RSA-SHA256 or stronger and a key of at least 2048 bits. A signature whose KeyInfo carries a certificate must use that one; a signature without KeyInfo is tried against each trusted certificate, as during a certificate rollover.
  • There is exactly one assertion, and it is not encrypted.
  • It is within its validity window, allowing 60 seconds of clock skew.
  • The identity provider reports success.
  • It names a stable subject: a non-transient NameID or principal_attribute.
  • It has not been used before. See Replay protection.
  • It is small and plain XML: a form of at most 1 MiB, at most 900 XML elements, no DTD, comments, or processing instructions.
Every assertion value a login uses (the subject, the attributes, and the conditions such as audience and validity window) is read from the assertion as its signature verified it, never from the rest of the document. Some checks compare values outside the assertion’s signature with what the gateway expects: RelayState is a field of the posted form, and the response’s Destination, InResponseTo, Issuer, and status are part of the response envelope, which a signature covers only if the identity provider signs the response as well. None of them is used as identity. Admission then applies as for OIDC.

Identity provider metadata

From a file. The file is read once. An unreadable or invalid file stops startup, and after the identity provider rotates its signing certificate you must replace the file and restart the gateway. From a URL. The gateway fetches the metadata at startup and again every metadata_refresh_interval, so a published certificate rotation is picked up without a restart. A failed refresh keeps the last good metadata. If the URL is unreachable at startup, the gateway still starts, logins answer 503 with identity_provider_unavailable, and the fetch is retried in the background (5 seconds, doubling to 5 minutes). Set require_discovery: true (PRO_SSO_REQUIRE_DISCOVERY=true) to make that a startup error instead. Metadata from either source is not used after its validUntil; logins are then unavailable until newer metadata is loaded.

What a refresh can change

A refresh may replace the signing certificates, the sign-on URL, and validUntil. It may not change the identity provider’s entity ID: such metadata is refused, the current metadata stays in use, and an error is logged. Restart the gateway to move to another entity ID. Whoever controls the metadata URL can publish a signing certificate of their own. Every refresh that changes the trusted certificates is therefore logged at warning level, with the SHA-256 fingerprints in added_fingerprints and removed_fingerprints:
Alert on that line. Startup logs the fingerprints it trusts.

Certificate pinning

To stop a rotation from being accepted automatically, list the SHA-256 fingerprints of the identity provider’s signing certificates:
Fingerprints are hex, case-insensitive, with optional colons. Only listed certificates are trusted, for a metadata file and a URL alike. Metadata with none of them stops startup; on a refresh it is refused and the last good metadata stays in use. To rotate, add the new fingerprint before the identity provider switches and remove the old one afterwards. Each step needs a restart.

Sessions and sign-out

A session ends at session_ttl, or at the assertion’s SessionNotOnOrAfter when that is earlier. An assertion whose SessionNotOnOrAfter has already passed is refused. Sign-out ends the GoModel session and then redirects to provider_logout_url when it is set, as for OIDC; see Sign-out across replicas.

Replay protection

Each assertion is accepted once. The gateway remembers the IDs of used assertions until they expire, in memory and in the configured storage backend.
  • PostgreSQL or MongoDB: a replayed assertion is refused on every replica that shares the storage. Two replicas that receive the same assertion at the same instant could both accept it; that also requires the person’s transaction cookie.
  • SQLite (the default): protection is per instance. Run a single replica, as for sign-out; the gateway logs a warning at startup.
  • Storage unavailable: the login is refused with replay_check_unavailable.

Limits

  • About 850 groups per person. Each group value is one XML element, and a response with more than 900 elements is refused with too_many_elements. The limit is not configurable. Filter at the identity provider: send only the groups assigned to the application, or those named in admin_groups and group_mappings.
  • Entra ID: at most 150 groups in an assertion. Above that, Entra ID sends http://schemas.microsoft.com/claims/groups.link instead of the groups, and while admin_groups or group mappings are set, the login is refused with groups_overage. Emit only the groups assigned to the application.
  • No login started at the identity provider. Logins must start at the gateway (/sso/login below any BASE_PATH). Unsolicited responses are refused.
  • No encrypted assertions. They are refused with encrypted_assertion.
  • No SAML single logout. The gateway sends no SAML logout request and processes none from the identity provider. Signing out ends the GoModel session; it ends the identity-provider session only through a provider_logout_url redirect.
  • One identity provider per gateway.
Last modified on November 18, 2026