Skip to main content

v26.3.13

v26.3.13​

Identity Federation user identifiers are now unique per upstream connection​

The sub claim an OpenID Connect Identity Federation app returns, and the id field its /oauth/userinfo endpoint returns, are now derived from the upstream connection that authenticated the person as well as from the identifier that connection asserted. Until now the app passed the upstream identifier through unchanged, so two connections behind one app could return the same identifier for two different people.

Every identifier an Identity Federation app returns is different after this upgrade. Directly configured SSO connections are unaffected: their identifiers do not change.

The ID token and the /oauth/userinfo response both carry two further claims:

  • upstream_sub holds the identifier the upstream provider asserted. It is permanent, and SAML single logout needs it.
  • legacy_sub holds the identifier the app returned before this change, for as long as OPENID_IDFED_LEGACY_SUBJECT is true. It is there so you can move your existing accounts across.

Moving your accounts across​

On each sign-in, look the account up by sub. If you find it, there is nothing more to do. If you do not, look it up by legacy_sub, and save sub in place of the old identifier.

Key your accounts on sub and on nothing else. Neither legacy_sub nor upstream_sub is unique across the connections behind an app, so neither can identify an account on its own.

That is about which value identifies an account, not about what you may keep alongside it. If you send SAML single logout requests you do need to store upstream_sub as well, as a property of the account rather than as its key. See below. legacy_sub is migration data only: use it to find the account, save sub, and keep nothing. Set OPENID_IDFED_LEGACY_SUBJECT=false once your applications have finished re-keying; that claim will be removed in a later release.

Single logout​

If you send SAML single logout requests, pass upstream_sub as the nameId rather than id. The upstream provider knows the person by that value; the id an Identity Federation app now returns is scoped to the app, and the provider will not recognise it.

If you set OPENID_SUBJECT_PREFIX​

That prefix, which is off unless you turned it on, no longer applies to Identity Federation apps; the tenant and product of an app never distinguished one of its upstream connections from another. legacy_sub still reproduces the prefixed identifier your integration stored, so the lookup above works either way.

If two people shared an 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.

Breaking changes​

Applications that store the sub or userinfo id of an Identity Federation app stop matching their existing accounts at this upgrade. Re-key them through legacy_sub as described above before setting OPENID_IDFED_LEGACY_SUBJECT=false. Without that, everyone signing in through an Identity Federation app appears as a new person.

Applications that send SAML single logout requests with the identifier they stored must switch to upstream_sub. Requests carrying the new id will not identify the person to the upstream provider.