Global Identity Providers

Global IDP is an extension of the Cloud Identity Plane (CIP) federation functionality. Global IDP also includes the ability to link a federated authentication request to existing user accounts in CIP , known as account linking.

Elements

This section defines the services, objects, APIs, and configurations that are used when configuring Global Identity Providers.

Services

The following CIP microservices are used in the federation process:

• IAM Services (iam-services): Manages creation and retrieval of CIP objects, including users, organizations, and IDPs. Also manages single sign-on (SSO) sessions.
• Federation Service (federation-service): Converts external federation assertions into internal CIP requests.
• AuthN UI (authn-ui): CIP’s login page and related pages for managing authentication flows. The typical non-federation login flow is presented by the AuthN UI as username and password authentication. Public IDPs are presented as icons on the AuthN UI main page.
• Admin UI (admin-ui): CIP’s UI for creating and managing objects, like users, organizations, and IDPs. Only privileged users, called admins, are permitted to access the Admin UI.

Objects and Attributes

The following objects are stored in the CIP database and are reflections of real-life elements:

• User: User may refer to an end user who is interacting with CIP and related systems, or to the actual user record stored in CIP or an external database.
• IDP: Identity providers are the source of a user’s identity. In the federation flows described in this document, IDPs are sources of user records that are external to CIP, like Google, SalesForce, or Active Directory. In CIP, a representation of an IDP is stored as an IDP configuration and managed through APIs; throughout this document, “IDP” may be used as a shorthand to refer to the IDP configuration object in CIP, rather than just the actual external IDP.
• Organization / Customer: Organizations are groupings of users in CIP. All users must belong to exactly one organization in CIP. The legacy name for organization in CIP is “customer” and may be used interchangeably.

The relevant attributes for these objects are described in Configuring attributes for global IDP federation flows (Operations docs)

APIs

The following APIs are related to federation flows. Several have updates in the Global IDPs epic. All of these APIs are found in the IAM Services service and are accessible through the API Gateway:

Service Configuration

See Configuring iam-services for global IDPs (Operations docs)

High Level Federation Flow

See Global IDP Federation Flows

Capabilities

Global IDP

Global IDP offers the following new capabilities:

1. A user can come from more than one IDP and map to the same CIP record;
2. Federated users are permitted to authenticate using ordinary authentication flows; and,
3. Although each IDP is still based on one organization, IDPs may be marked as global (organization-independent) and organizations may subscribe to them if they want to enable their users to authenticate from them.

The format of remoteIdentifiers is improved to pair the IDP hash with each user identifier, separated by a delimiter ("#"). For example, if a user with identifier “testuser1” comes from IDP with hash “1234”, then the remote identifier “1234#testuser1” will be stored in that user’s remoteIdentifiers.

The federatedIdpHash field is deprecated. This feature includes “data healing”, which is meant to clean up user records and update their data format. Specifically, when a user with an old remote identifier format and federatedIdpHash completes federated authentication, their federatedIdpHash is automatically removed and their old remote identifier is updated to the new format (with IDP hash included).

A single instance of a global IDP configuration may be used by many organizations. New APIs have been added to enable admins to subscribe, or unsubscribe, organizations to/from global IDPs. Since global IDPs are shared between different organizations, they are protected with higher security measures than organization-specific IDPs. A new entitlement, “ADMIN_MANAGE_GLOBAL_IDPS”, must be owned by an admin before they can create, modify, or delete any attributes of a global IDP, and before they can set an IDP as global.

Account Linking

Also solved in this feature is the ability to link a federated authentication request to existing user accounts in CIP through values in the user account. This is referred to as account linking. For a given IDP, the accountLinkingAttributes can be set with a priority-ordered list of attribute names. If a user record is not found by its remoteIdentifiers (which is derived from the primary identifier mapped from the correlationIdentifierFieldName and the IDP hash), then a secondary search will look for CIP users whose attributes match the incoming claims from the external IDP. For example, if account linking is set up for CIP attribute uid and during federated authentication a claim “testuser1” is mapped to uid, and if no other user is found with the corresponding remote identifier, then a user in CIP with uid = “testuser1” will be used for this authentication.

On the AuthN UI front page, any public IDPs which are global will be displayed for unidentified users. If the user begins entering their identifier, IDPs with which they previously federated are displayed as well.

For admins listing IDPs in the Admin UI, global IDPs are visible to the admin, in addition to IDPs belonging to the admin’s organization.

Features In Detail

Topics are arranged by category.

Retrieving IDPs - Get, List, Discovery

There are four (4) APIs for retrieving IDPs: Get IDP, List IDPs, Get IDPs for User, and IDP Discovery (see API table above).

Previously, Get and List IDPs would only permit retrieval of IDPs in the same organization as the current session context’s organization. However, global IDPs are now able to be retrieved, even if they belong to a different organization.

Get IDPs for User and IDP Discovery are APIs that accept an optional user identifier and, in the case of the former, an optional customer (organization) parameter. Previously, if the user was found, only the user’s single IDP from their federatedIdpHash would be returned. Otherwise, the specified organization’s public IDPs would be returned. Now, if the user is found, the public IDPs of their organization are returned alongside the user’s other IDPs. Furthermore, global IDPs that are public are returned, even if they belong to a different organization than the user.

Modifying IDPs - Create, Update, Delete

For functionalities that modify IDPs, there are no changes for non-global IDPs. Global IDPs, on the other hand, are only allowed to be modified by users who have the entitlement “ADMIN_MANAGE_GLOBAL_IDPS” (the name is configurable). The reason for this is, global IDPs are shared between many organizations, so changes must be handled by only certain high-ranking admins.

• For Create IDP, the “ADMIN_MANAGE_GLOBAL_IDPS” entitlement is needed if creating an IDP with the isGlobal attribute set to true.

• For Update IDP, the “ADMIN_MANAGE_GLOBAL_IDPS” entitlement is needed if changing the isGlobal attribute to true, or if modifying any attribute of an IDP that is already marked as global.

• For Delete IDP, the “ADMIN_MANAGE_GLOBAL_IDPS” entitlement is needed if deleting an IDP with isGlobal set to true.

Organization subscription to global IDP

In order for users within an organization to be able to federate with a global IDP, the organization must subscribe to that IDP.

The functionality for subscribing or unsubscribing an organization to a global IDP comes in two flavors:

• Admin (subscribe/unsubscribe specified organization): These APIs allow the user to choose an organization’s subscription to an IDP to manage. Admins must be permitted to modify the specified organization; i.e. it must exist in their customers attribute, or they must have the special entitlement “ADMIN_ALL_CUSTOMERS”.
• Self (subscribe/unsubscribe my organization): These APIs allow the user to manage the subscription of their own organization to an IDP. The organization is based on the current authentication context of the user.

When subscribing an organization to an IDP, the IDP must exist and be global (isGlobal = true). When unsubscribing an organization from an IDP, the IDP need not exist or be global; this allows cleanup of stale data to be performed, in case an IDP was deleted or its global status changed after an initial subscription.

SAML Authentication Complete API

The logic within the SAML Authentication Complete API has increased in complexity to support identifying users belonging to multiple IDPs and organizations. This section describes this API’s logic in detail.

Elements of the API

In a federation flow, the Federation Service calls the SAML Authentication Complete API. This API accepts a request body with the following parameters:

• idpConfigurationIdentifier (string): The unique hash of the IDP from which the user authenticated.
• userIdentifier (string): The value of the unique identifier for the user, which had been mapped from the federation assertion’s claims by the Federation Service based on the IDP’s correlationIdentifierFieldName.
• user (object): The set of attribute name-value pairs which were mapped from the federation assertion’s claims by the Federation Service based on the IDP’s customMapping. In this section, these attributes will be referred to as “external user attributes”.

If a user who matches the request is identified in the CIP datastore, their existing attributes are also considered when resolving the final attribute set of the user. These are referred to as “internal user attributes.” Note that if there is no matching user record in CIP, there will be no internal user attributes.

For certain user attributes that must exist in a CIP record, there is a set of default values that are applied if not found through the above sources. These are referred to as “default user attributes.”

Identifying the User

One of the goals of the SAML Authentication Complete API is to identify a user account in CIP which corresponds to the federated authentication in-progress. There are two means by which it accomplishes this: remote identifiers and account linking.

Identifying through Remote Identifiers

Remote identifiers are the primary mechanism for finding users in CIP who have previously federated, since this attribute exists solely for federated authentication purposes. Before account linking was introduced in this feature to identify native (non-federated) CIP users, this was the only means to find users in CIP during federated authentication. The algorithm is as follows:

Using the userIdentifier and idpConfigurationIddentifier (IDP hash), the API searches for users who have remoteIdentifiers containing either "<idpHash>#<userIdentifier>" (the updated, hash-delimited format for remoteIdentifiers) or "<userIdentifier>" (the legacy format).

• If a single user is found with the updated format, it is selected.
• If multiple users are found with the updated format, an error is returned.
• If no users are found with the updated format, but a single user is found with the legacy format and federatedIdpHash matching the IDP hash, it is selected.
• If no users are found with the updated format, but multiple users are found with the legacy format and federatedIdpHash matching the IDP hash, an error is returned.
• Otherwise, no user is selected.

Note that if users are found with the legacy format but federatedIdpHash matching a different IDP than the one in the request, these users are not selected.

If no users are selected, the API falls back to account linking.

Identifying through Account Linking

If no users are found using the remote identifiers algorithm above, account linking may be used to find a CIP record. Account linking attempts to find a CIP record using external user attributes (mapped from the federation claims).

Account linking depends on the accountLinkingAttributes field of the IDP configuration and the external user attributes that are mapped from federation claims into the user part of the API request body. accountLinkingAttributes is a prioritized list of CIP attribute names, for which a user record will be searched in order. An example configuration is as follows:

[
  {
    "attributeName": "uid",
    "priority": 0
  },
  {
    "attributeName": "identifierEmails",
    "priority": 1
  },
  {
    "attributeName": "defaultEmail",
    "priority": 1
  },
  {
    "attributeName": "identifierMobiles",
    "priority": 2
  },
  {
    "attributeName": "defaultMobile",
    "priority": 2
  }
]

An example set of external user attributes is the following:

{
  "uid": "testuser1",
  "firstName": "Test",
  "lastName": "User",
  "defaultEmail": "testuser1@test.cloudentity.com",
  "identifierEmails": ["testuser1@test.cloudentity.com"],
  "identifierMobiles": ["5555555555"]
}

This is the account linking algorithm, using the above configuration as an example:

• For all attributes in the accountLinkingAttributes configuration, any corresponding values among the external user attributes are found and all users matching any of these attributes are retrieved from the datastore.

• If no users are found, or no accountLinkingAttributes are configured, the algorithm terminates with no user found.

• The attribute names corresponding external values are grouped by priority, from lowest priority integer to highest. In the above example, this would result in the following data structure:

  [
    {
      "uid": "testuser1"
    },
    {
      "defaultEmail": "testuser1@test.cloudentity.com",
      "identifierEmails": ["testuser1@test.cloudentity.com"]
    },
    {
      "identifierMobiles": ["5555555555"]
    }
  ]
  

• Starting with the highest priority attribute group, matching users are identified.

  • If one matching user is found for the highest priority, that user is selected and the algorithm terminates.

  • If multiple users are found, the one whose organization (customer attribute) matches the IDP’s organization is selected.

  • If multiple users are found with the organization matching the IDP’s organization, an error is returned.

• If no users are found for the highest priority, the next priority is evaluated until a single matching user record is selected.

It is important to note that account linking will not be used if a user was found by remote identifiers, or if no accountLinkingAttributes are configured for the IDP.

User Attribute Resolution and Data Healing

User Attribute Resolution and Data Healing includes default user attributes. If a new user is JIT provisioned, or if an existing user is updated, the external, internal, and default user attributes must be merged by the API.

In order to unify basic data for CIP user records, the following values will always be set if they do not exist for a user upon federated authentication (any existing values in the user record will be retained):

• status: “active”
• customer: IDP’s customer
• customers: IDP’s customer
• entitlements: Set of entitlements configured in IAM Service configuration (see configurations above). Default configured value is empty array.
• entitlementGroups: Set of entitlements configured in IAM Service configuration (see configurations above). Default configured value is ["FEDERATED_USER_ENTITLEMENT_GROUP"].
• authSecret: System-generated TOTP secret
• authSecretAccepted: false

In addition, the IDP hash and user identifier will be added in the format "<idpHash>#<userIdentifier>" to the user’s remoteIdentifiers array, any existing remoteIdentifiers will be updated to the new format, and the user’s legacy federatedIdpHash will be removed if it exists.

Values from external attributes override any default or internal attributes if the user does not exist, or if the IDP’s updateProvisionedUser flag is set to true.

If the IAM Service configuration areVerifiedAddressesIdentifiers is set to true, and verifiedEmails or verifiedMobiles is being set from external attributes, then identifierEmails and identifierMobiles, respectively, will be updated to match.

Organization Resolution

The final organization of a user, which will be stored in the user’s customer attribute, must be resolved and validated by the API logic. The logic for resolving the customer is:

• If customer is provided in the external attributes from the request body, and the user is either not found or the IDP’s updateProvisionedUser is true, this customer value will be used.
• If the user is found and already has a customer, this will be retained.
• Otherwise, the IDP’s customer will be used.

In some cases, the resolved customer from the above algorithm does not match the IDP’s own customer setting. In this case, the IDP must be global, and the resolved organization must exist and be subscribed to the IDP. Otherwise, an error is returned.