SAML Federation

SAML Federation is an enterprise feature and you need to have an enterprise license to use this feature.

This feature allows you to federate multiple Identity Providers (IdPs) without needing any additional plugins or code changes. Extremely useful in cases where the SAML support is restricted to a single provider and you need to support multiple IdPs. Contact us to find out more.

SAML Federation Flow

Here is how the SAML Federation flow works if you are using Ory Polis as a SAML IdP and want to federate with another identity provider (IdP) (Eg: Okta):

• The user accesses the Service Provider's (SP) login page
• The user clicks on the "Login with SAML" button
• The SP sends SAML Request to Ory Polis's SSO endpoint
• Ory Polis displays the list of IdP available for the user to choose from (if there is more than one IdP) based on the requested tenant and product combination
• Ory Polis redirects the user to the chosen IdP for authentication
• After successful authentication, IdP sends (POST) SAML Response to Ory Polis's ACS endpoint
• Ory Polis process SAML Response from the IdP and create a new SAML Response to send (POST) back to the SP's ACS endpoint
• SP process SAML Response from Ory Polis and create a new session for the user (Depending on the SP's implementation)

User identifiers

This section applies to OIDC Federation Apps only. A SAML Federation App is unaffected: the SAML Response it sends to the Service Provider carries the NameID the upstream Identity Provider asserted, exactly as it did before.

An OIDC Federation App fronts several Identity Providers behind one issuer, so the identifier it returns for a user is derived from the upstream connection that authenticated them as well as from the identifier that connection asserted. Two connections behind one app therefore never return the same identifier for two different people, which they could otherwise do whenever both Identity Providers happen to use the same local identifier for someone.

That identifier is the sub claim in the ID token and the id field from the userinfo endpoint. Store your accounts under that value.

Two further claims are returned alongside it, in both the ID token and the userinfo response:

• upstream_sub holds the identifier the upstream Identity Provider asserted. Pass this as nameId when you send a single logout request, because the upstream provider knows the user by this value. Do not store an account under it — the connections behind one app can assert the same value.
• legacy_sub holds the identifier the app returned before identifiers became connection-scoped, while OPENID_IDFED_LEGACY_SUBJECT is true. If you have accounts stored under the old identifier, look them up by legacy_sub on the next sign-in and save sub in its place, then set that variable to false. Do not store legacy_sub itself; the claim will be removed in a later release.

If two people were previously sharing one identifier, they now receive different ones. The account you already hold follows whichever of them signs in first and the other is provisioned as a new account, so review those by hand.

Visit Create SAML Federation App to learn how to create and configure a SAML Federation App.