SAML in your tenant

Your tenant as identity provider

Add each application on SAML Applications: its entity ID, its assertion consumer service URL (https), optionally its logout URL and its signing certificate, the NameID format, and the attributes it receives (user ID, email, first name, last name, user name, groups or directory roles). Give the application your tenant's details from the same page:

Entity ID     https://<your tenant>
Metadata      https://<your tenant>/saml/metadata
Single sign-on https://<your tenant>/saml/sso   (HTTP-Redirect or HTTP-POST)
Single logout  https://<your tenant>/saml/slo   (HTTP-Redirect)

An authentication request must come from a registered entity ID, and the response goes only to the registered assertion consumer service URL, whatever the request names. A request older than five minutes is refused. When you require signed requests, or a request carries a signature, it is checked against the application's certificate. If the person is not signed in, they sign in to your tenant first, with its own rules and second steps; ForceAuthn asks for a new sign-in and IsPassive answers NoPassive instead of showing a page. A request may also ask for a NameID format, a binding for the answer and an authentication context. Your tenant answers with the application's own NameID format, so a NameIDPolicy asking for another format is refused with InvalidNameIDPolicy; one asking for any format (unspecified) is fine. A ProtocolBinding other than HTTP-POST is refused with UnsupportedBinding. A RequestedAuthnContext is compared, using its exact, minimum, better or maximum comparison, with your tenant's own ordering of sign-ins, weakest first: unspecified; a secret over TLS (Password and PasswordProtectedTransport: a password, an email or authenticator code, a sign-in link or a push approval); a passkey (https://refeds.org/profile/sfa); and two factors (https://refeds.org/profile/mfa), such as a passkey that verified the person or a password with a second step. A sign-in at another identity provider counts as unspecified unless that provider vouched for two factors. So a passkey meets a request for at least PasswordProtectedTransport, and the assertion names the strongest class that describes the sign-in, or for exact the requested class that describes it. When the person's sign-in does not meet the request but they have a way to sign in that would, such as their password, they are sent back through sign-in once; otherwise, or if that sign-in still does not meet it, the answer is NoAuthnContext. Each application's Requested authentication context setting can instead ignore what the application asks for, and the assertion then names how the person actually signed in. The response is posted by the browser (HTTP-POST) with one assertion signed with RSA-SHA256, its audience the application's entity ID, a bearer confirmation for the assertion consumer service, and a lifetime from 60 to 600 seconds (300 by default). You can also sign the whole response.

The persistent NameID is a value made for that application alone, so two applications cannot match their users through it. Email sends the person's address, and unspecified sends the tenant's user ID. Applications listed in the app launcher open from the person's Applications page with an assertion that answers no request (IdP-initiated), carrying the application's default RelayState.

Signing keys and metadata

Your tenant makes an RSA signing key with a self-signed certificate, valid two years, when it first needs one. To change keys, generate a new one: it signs from then on, and the previous key starts retiring but stays in your metadata, so applications can trust the new certificate before you disable the old one. Only a retiring key can be disabled, so one key always signs. Your metadata lists both roles of your tenant: identity provider and service provider.

Single logout

An application can end a person's sign-in with a LogoutRequest by HTTP-Redirect. Because the request can end the person's sessions on every device, it must be signed with the application's certificate, addressed to your tenant's logout URL and no more than five minutes old. An application without a certificate on file cannot use single logout. The request names the person and, optionally, one or more SessionIndex values: your tenant ends each listed SAML session, or every session of that person at the application when none is listed, and the browser sessions they came from. It then tells the person's other SAML applications from those browser sessions, one at a time: the browser carries a signed LogoutRequest by HTTP-Redirect to each application's logout URL, and the application answers at your tenant's logout URL with a LogoutResponse, signed with its certificate if it has one on file. Finally your tenant answers the application that asked with a signed LogoutResponse at its logout URL. If any application has no logout URL, or did not confirm, that answer carries the second-level status PartialLogout, so the application can tell the person to sign out of the others too. The browser has ten minutes to finish; a logout left unfinished never reaches the application that asked.

Signing out on your tenant's own pages works the same way. The person's session here ends first, then each SAML application they opened from that browser session is sent a signed LogoutRequest in turn and answers at your tenant's logout URL, and the browser finishes at the sign-in page. If any application has no logout URL or did not confirm, the person sees a page saying some applications could not be told, so they can sign out of those too. A sign-out that an OpenID Connect application starts at /oidc/logout does not yet reach SAML applications.

Trusting a SAML identity provider

On Federation, add a SAML provider from its metadata URL, from metadata you paste, or from its entity ID, sign-on URL and signing certificate (an RSA key of at least 2048 bits or an EC P-256 key, not expired). A certificate that cannot be used is refused with the reason: unreadable, an unsupported key, or expired. Your tenant sends sign-in requests by HTTP-Redirect, so the provider's metadata must offer a sign-on address for that binding. When the provider is set to receive signed requests, your metadata says so. Give the provider your tenant's service provider details: entity ID https://<your tenant> and assertion consumer service https://<your tenant>/saml/acs. Each provider's NameID format to ask for sets the NameIDPolicy in your tenant's requests: any format the provider is set to send (unspecified, the default), persistent, email address or transient. A provider that cannot send the format asked for refuses the sign-in. Connections are keyed on the NameID the provider sends, so it must stay the same for a person; a transient NameID changes at every sign-in. Your tenant sends an authentication request by HTTP-Redirect, signed when you choose, and checks the response: its destination (which a signed response must name), the request it answers, the issuer, a signature on the assertion or on the whole response, the audience, the bearer confirmation and its times, an AuthnStatement saying the person signed in, and that the assertion was not used before. Only the element the signature covers is read, so a moved or copied assertion is refused. Encrypted assertions are not accepted. Responses that answer no request (IdP-initiated) are refused, because nothing ties them to this browser. Connecting and creating accounts then work as for any identity provider, with the NameID as the subject.

The SAML bearer grant

With the SAML bearer assertion grant allowed in Flow Policy and for a client, and that client listed in the SAML provider's Clients that may exchange its assertions, the client can post grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer and the assertion, base64url encoded, to the token endpoint (RFC 7522). The assertion must be signed by the provider, addressed to your tenant or its token endpoint, confirmed for the token endpoint, unexpired, and not used before. Its NameID finds the user only through a connection to that provider. No ID token or refresh token is issued, since nobody signed in here.

Limits, Audit and Logs

A tenant can have 20 SAML applications and 4 signing keys in use. Requests and answers are recorded under saml.sso (saml_request_received, saml_assertion_issued) and saml.slo (saml_logout_started, saml_logout_propagated and saml_logout_confirmed for each other application, saml_logout_unreachable for one without a logout URL, then saml_logout_completed or saml_logout_partial), naming the application by ID; refusals have their own reasons, such as saml_acs_mismatch, saml_request_expired, saml_signature_invalid, saml_audience_mismatch and saml_assertion_replayed. Changes to applications and keys are recorded in Audit. BTL Admin has the same SAML Applications page for the BTL organization.