Global IDP federation flows

This article describes the overall federation flow for users from different organizations who want to share a common (global) Identity Provider.

NOTE: For all flows described in this article, IDPs are external and CIP acts as the service provider (SP).

High-Level Flow

This section describes the overall federation flow for users from external IDPs interacting with CIP.

Setup - Admin

Configure iam-services

First, a system admin must set the iam-services values properly for the entire CIP deployment. The following attributes are of particular note:

enableJIT: Just-In-Time provisioning. If JIT is enabled and a user is not found during federated authentication, it will be created in the CIP datastore. If JIT is disabled, users must be placed in the CIP datastore by another process; when a user is not found on authentication, an error will be returned.
areVerifiedAddressesIdentifiers: If verified addresses are identifiers, then anytime verified emails or mobiles are mapped from an external IDP claim, they will be added as an identifier for the CIP user. Identifiers must be globally unique and can be used for non-federated authentications.

Configure Identity Provider

Next, an admin must perform some setup steps in the Admin UI (or through API calls) before federated authentications can be enabled.

To create a global IDP using the Admin UI, navigate to Identity Providers and click on Register Identity Provider. In the form to register an identity provider, check the Global checkbox.

Create IDP

To update an existing IDP’s global status using the Admin UI, navigate to Identity Providers and select the IDP to be updated. In the actions menu for the IDP, click on Update IDP. In the update IDP form, check the Global checkbox.

Update IDP

An IDP configuration needs to be created to represent an external IDP:

The IDP should be marked as public if it should appear on the AuthN UI before a user’s first federated authentication.
The IDP’s customMapping is set to show how external claims map into CIP attributes. For example, if a claim email comes from the external IDP’s assertion, it may map to a CIP user’s defaultEmail, verifiedEmails and uid.
The IDP’s correlationIdentifierFieldName is the name of the external claim from which the user’s unique identifier in CIP should be derived.
The IDP should be marked as global if users from multiple organizations should be able to use it for authentication.
The IDP’s accountLinkingAttributes need to be set to link a federated authentication to existing users who have not federated before.
The IDP needs to be activated before it can be used for authentication.

IDPs are created in the context of a specific organization. If they are marked as non-global, only users within that organization can federate with that IDP. If they are marked as global, other organizations can subscribe to this IDP so their users can federate.

If a global IDP is to be used by an organization, an admin needs to subscribe the organization to that IDP.

To subscribe or unsubscribe an organization to/from a global IDP using the Admin UI:

Navigate to Organizations and select the organization to be subscribed or unsubscribed. In the actions menu of the organization details view, open the fly-out menu for more options, and select Subscribe organization to a global IDP or Unsubscribe organization from a global IDP (the unsubscribe option will not be shown if there are no subscribed global IDPs for that organization)

Subscribe an Organization to a Global IDP (fig. 1)

In the action form, select an available global IDP to subscribe to or unsubscribe from. Make a careful note of the IDP hash value, as it is possible for two or more IDPs to have identical descriptions. Click Subscribe or Unsubscribe to confirm.

Subscribe an Organization to a Global IDP (fig. 2)

If JIT is disabled, any users must be pre-created by some other means. An admin can create users through the Admin UI, users can self-register through the AuthN UI, or a system admin can create users directly in the datastore. The user must be active to authenticate.

To subscribe or unsubscribe the current organization to/from a global IDP (in the screenshot below, the alias of the organization under which the admin is currently signed in is shown in the top-right navigation, as indicated by the red arrow):

Navigate to Organizations, and next to the Create Organization button, open the fly-out menu for more actions, and select Subscribe current organization to a global IDP or Unsubscribe current organization from a global IDP.

Subscribe the Current Organization to a Global IDP (fig. 1)

In the action form, select a global IDP to subscribe to or unsubscribe from (if available). Make a careful note of the IDP hash value, as it is possible for two or more IDPs to have identical descriptions. Click Subscribe or Unsubscribe to confirm.

Subscribe the Current Organization to a Global IDP (fig. 2)

Note: Setting up federation between CIP and an external IDP is outside the scope of this document.

Federated Authentication - User

Federation starts when a user goes to the Federation Service’s Authenticate endpoint in CIP: /federation/authenticate/<idp-hash>. For public IDPs, this can be conveniently accessed by clicking the IDP’s icon in the AuthN UI. The IDP’s configuration is retrieved in CIP and the user is sent to the IDP’s configured redirect URL. After authenticating with the external IDP, a federation assertion is sent back to the Federation Service. This service translates the claims of the assertion into CIP attributes and prepares a request to the SAML Authentication Complete API in IAM Services. The request body includes the IDP hash, a unique identifier for the user mapped from the IDP’s correlationIdentifierFieldName, and a set of user attributes mapped from the assertion claims, according to the IDP’s customMapping.

The SAML Authentication Complete endpoint is responsible for:

Finding the user record in CIP or provisioning the user if the user is not found and JIT is enabled;
Validating that this user is permitted to federate with this IDP; and,
Creating an SSO session in CIP and returning the session token.

The result of this flow is a representation of the external IDP’s user record in CIP, and the user is authenticated in CIP and can use its services using the returned SSO token.