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. Withprotocol: oidc, everysamlsetting 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.
Configure SAML
The shared settings in
Identity and admission keep their meaning.
Register the gateway
The gateway publishes two URLs, both below anyBASE_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_failedwhileadmin_groupsor group mappings are set. - An assertion without the groups attribute that carries Entra ID’s
http://schemas.microsoft.com/claims/groups.linkinstead (sent for people in more than 150 groups) is refused withgroups_overagewhileadmin_groupsor group mappings are set. See Limits. - Changing
protocol, or the attribute thatuser_path_claimorgroups_claimresolves to throughsaml.attributes, ends existing sessions, as described in When the configuration changes. allowed_domainsand the defaultuser_path_claim: emailread the attribute named or aliasedemail. The user path is lower-cased only withuser_path_claim: emailoruser_path_case_insensitive: true.- The principal is the NameID, or
principal_attributewhen set. A transient NameID changes at every login and is refused unlessprincipal_attributeis 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_claimthat reads it, which includes the defaultuser_path_claim: email;allowed_domains;groups_claimthat reads it, whenadmin_groupsor group mappings are set.
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, andInResponseTomust match. - It is addressed to this gateway.
DestinationandRecipientequalacs_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
KeyInfocarries a certificate must use that one; a signature withoutKeyInfois 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.
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 everymetadata_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, andvalidUntil. 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:
Certificate pinning
To stop a rotation from being accepted automatically, list the SHA-256 fingerprints of the identity provider’s signing certificates:Sessions and sign-out
A session ends atsession_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 inadmin_groupsandgroup_mappings. - Entra ID: at most 150 groups in an assertion. Above that, Entra ID sends
http://schemas.microsoft.com/claims/groups.linkinstead of the groups, and whileadmin_groupsor group mappings are set, the login is refused withgroups_overage. Emit only the groups assigned to the application. - No login started at the identity provider. Logins must start at the
gateway (
/sso/loginbelow anyBASE_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_urlredirect. - One identity provider per gateway.