How to implement identity federation
Identity federation lets users authenticate with a trusted upstream identity provider (IdP). Client applications continue to use the Connect2id server as their OpenID provider, regardless of how users authenticate upstream.
The authorisation session web API of the Connect2id server decouples authentication from the server. Integrators can use their login handler to connect upstream IdPs through OpenID Connect, SAML or another standard, proprietary or legacy sign-in protocol, while controlling provider selection, user identifier mapping and local authentication policies.
In this arrangement, the login handler acts as a relying party (RP) to the upstream IdP. This is distinct from the downstream client application, which acts as an RP to the Connect2id server.
Steps
1. Add an upstream sign-in option
When the authorisation session web API returns an authentication prompt, the login handler can offer a button or account chooser for signing in with an upstream IdP.
Alternatively, select the provider according to a routing policy. For example, ask for the user’s email address and use its domain to choose an organisation’s IdP. This selects where to authenticate the user; it does not establish their identity.
2. Register the login handler with the upstream IdP
Register the login handler as a client or RP with each upstream IdP. For
OpenID Connect, this typically involves registering
a callback URL (redirect_uri) for the authorisation code flow and obtaining
a client_id and client credentials.
Choose a strong client authentication method supported by the provider and
your deployment, preferably an asymmetric method such as private_key_jwt.
Store credentials securely on the server side. Use the authorisation code
flow with PKCE (S256) where supported by the provider.
3. Choose a client library
Use a maintained library that supports the upstream protocol and handles response validation and protocol security checks. Choose one that fits your login handler’s language, framework and deployment environment.
For Java and OpenID Connect, options include the open-source Nimbus OAuth 2.0 / OpenID Connect SDK and framework integrations such as Spring Security or pac4j. Choose the appropriate client module for each upstream protocol.
4. Define a user identifier mapping
Define how upstream identities map to local user IDs, such as UUIDs. A persisted mapping lets the same upstream identity resolve to the same local user on subsequent logins.
For OpenID Connect, identify an upstream user by the combination of the
issuer (iss) and subject (sub) from a validated ID token. A subject value
alone is not unique across providers. Email addresses are not stable user
identifiers and must not be used as the mapping key.
A mapping can also link multiple upstream identities to one local user, so the user can sign in through either Google or Apple, for example:
| Local ID | Upstream issuer (iss) |
Upstream subject (sub) |
|---|---|---|
| u0001 | https://accounts.google.com | eiQu8ziu |
| u0001 | https://appleid.apple.com | iuYui0ro |
Link identities only after verifying that the user controls both accounts, or through an authorised administrative process. Matching email addresses alone is insufficient.
5. Make upstream claims available
If the login handler requests claims and the upstream IdP supplies them, make the required attributes available through the Connect2id server’s claims source SPI.
For example, store or cache the claims in a database keyed by the local user ID, retaining their source:
| Local ID | Source | Email verified | |
|---|---|---|---|
| u0001 | [email protected] | true |
Define which providers are trusted to supply each attribute and when cached
values must be refreshed. Treat claims such as email_verified as assertions
made by the upstream provider.
6. Implement the flow
-
The downstream client sends the user’s browser to the Connect2id server’s authorisation endpoint, implemented by the login handler.
-
The handler submits the request and any existing session cookie to the authorisation session web API. If authentication is needed, the API returns an authentication prompt.
-
The handler offers the configured authentication options, such as local authentication or sign-in with an upstream IdP.
-
If an upstream IdP is selected, the handler invokes its client library to initiate authentication. For OpenID Connect, this normally redirects the browser to the provider. Preserve the pending authorisation session ID and upstream transaction state securely, bound to the initiating browser session. Keep the upstream and downstream protocol state distinct.
-
At the upstream callback, the client library completes the protocol flow and validates the response. For OpenID Connect, this includes exchanging the authorisation code and validating the ID token, expected issuer, audience and applicable
stateandnoncevalues. Only after successful validation should the handler resolve the local user ID and update any cached claims. -
The handler submits the mapped local user ID to the pending authorisation session through a server-side API request:
PUT /authz-sessions/rest/v3/g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE HTTP/1.1 Host: c2id.com Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6 Content-Type: application/json { "sub" : "u0001" } -
The handler processes the Connect2id server’s next response, obtains local consent if prompted, and relays the final authorisation response to the downstream client. See the authorisation session API reference for the remaining steps.