Products » Connect2id server » Documentation » Old versions » Connect2id server 7.x - 9.x » Guides »

How to implement identity federation

Identity federation is the chaining of identity providers (IdPs). It enables an end-user to get authenticated with a second, trusted IdP. To the relying party (RP) the result should be indistinguishable.

The authorisation session web API of the Connect2id server, which primary purpose is to bind a login page (handler), can also be used to implement federation. The federated (upstream) IdPs can be linked via any sign-on protocol, standard or legacy.

Steps

1. Add sign-in button

To give the end-user the choice to sign-in with a federated IdP add a button / account chooser for it to the login page. You may also use some heuristic rule, for example letting the end-user enter their email address and using its domain name to determine the appropriate IdP. The option to sign-in with a federated IdP should be presented to the end-user when the authorisation session web API prompts the login page to authenticate the end-user.

2. Register login page as RP

Register the login page as an RP with the federated IdP. For an upstream IdP that supports OpenID Connect this would typically mean registering a callback URL (redirect_uri for the OAuth 2.0 authorisation code flow) and obtaining the necessary client_id and credential.

For best security we recommend registering the RP for the strongest available client authentication method that is made available by the upstream IdP.

3. Choose client library for the RP

To implement the RP logic use a suitable library. If you're integrating the federated IdP via OpenID Connect and your login page runtime is Java, you can use our own open source OpenID Connect SDK directly, or via a web framework, such as Spring Security or Pac4j, whichever is be easier to use.

Spring Security and Pac4j also support SAML.

4. Define an end-user ID mapping

You will normally need to create and persist a mapping between the ID for end-user that is assigned locally (e.g. a GUUID) and the end-user ID that is returned by the federated IdP.

If you support multiple federated IdPs, such as a Google and Twitter, this would allow an end-user to potentially sign-in with both.

Local ID Google ID Twitter ID
u0001 eiQu8ziu iuYui0ro

5. Cache end-user attributes / claims

If the RP requests claims (attributes) about the end-user and the federated IdP makes such available, you will need to cache them in a database and make them available for retrieval via the claims source SPI of the Connect2id server.

Example:

Local ID Source Email Email verified
u0001 google [email protected] true

6. The flow

The flow with a federated IdP looks like this:

  1. The RP sends the browser to the login page of the Connect2id server.

  2. If the end-user doesn't have a valid session with the Connect2id server, the authorisation session web API will bring up an authentication prompt.

  3. At this point the login page gives the end-user options to authenticate locally or to sign-in with a federated IdP.

  4. If a federated IdP is chosen, the RP client code for it should be called to initiate the flow. This will typically involve redirecting the end-user to the login page of the federated IdP. Before that the state should be saved (in a browser cookie or on the server side).

  5. When the flow with the upstream IdP is completed (the browser is redirected back to the login page of the Connect2id server), the RP client will receive an end-user ID and possibly attributes (claims). These should be persisted / cached locally.

  6. The mapped local end-user ID should be submitted in the authorisation session to the Connect2id server. The Connect2id server will then continue the flow as normal.

    Example:

PUT /authz-sessions/rest/v3/g6f5K6Kf6EY11zC00errCf64yLtg9lLANAcnXQk2xUE HTTP/1.1
Host: c2id.com
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "sub" : "u0001"
}