Federate with an external IdP using OIDC

This topic describes how to add and configure an external IdP in the Identity Administration portal using OpenID Connect (OIDC).

Overview

Consider the following scenario in which a CyberArk Identity administrator has configured an OpenID provider as an external IdP:

When you trust another IdP in this manner, its users may access one or more CyberArk Identity applications.

This approach delivers several benefits, including:

  • Eliminating the need to create new credentials when accessing your applications.

  • Reducing your security risk by delegating password storage to the external IdP.

  • Centralizing access to applications by mapping external IdP groups to CyberArk Identity groups and roles.

Step 1: Add an external IdP

  1. Go to Settings > Users > External Identity Providers, and select Add.

  2. Enter a unique value as the External Identity Provider Name.

  3. Select OIDC in the Federation Type drop-down menu.

Step 2: Map external groups to CyberArk Identity groups

You can create rules to map an external IdP user's group to a CyberArk Identity group. This allows external users to access applications using CyberArk Identity groups and roles.

Each CyberArk Identity group must be associated with at least one role. For more information, see Add members to an existing role.

  1. Select Group Mappings > Add to create a mapping of group attribute values.

  2. Enter the source role or group into the Group Attribute Value column. The external IdP assigns the user this value.

  3. Select an existing CyberArk Identity group in the Group Name column or enter a new one.

Step 3: Configure inbound trust

As an OpenID provider, the external IdP requires CyberArk Identity to acquire OIDC tokens. CyberArk Identity gets the tokens based on the external IdP's public .well-known/openid-configuration metadata.

  1. Go to Inbound Metadata.

  2. Select the grant type associated with the OIDC client.

    CyberArk Identity supports two grant types: Authorization Code and Authorization Code with PKCE. You may optionally choose the latter by selecting the Enable PKCE checkbox.

  3. Enter the Client ID and Client Secret that CyberArk Identity should use to request tokens on behalf of external IdP users.

    The external IdP provides both of these values.

  4. Enter the OpenID provider Metadata URL provided by the external IdP. This URL should end with .well-known/openid-configuration.

Step 4: Configure outbound trust

There are several key authentication events that require the external IdP to redirect the user. CyberArk Identity automatically creates the redirect pages needed to handle these events.

Go to Outbound Metadata and copy the following values into the OpenID provider's SSO configuration:

Redirect URLs
Redirect URL Description

Redirect URL

The authorization code grant type is a redirection-based flow. This callback handler receives the code.

Initiate login URL

The callback users already authenticated in the external IdP are sent to in order to trigger an authorization request.

Post-logout redirect URL

The URL the user should be redirected to after signing out of CyberArk Identity.

This action applies if you configured single logout in CyberArk Identity for an external IdP that has a post-logout URI and the external IdP in the Identity Administration portal uses OpenID Connect (OIDC). In the external IdP, change the Post-logout redirect URL to match the single logout URL that is used in the web application's service provider configuration.

For information on configuring the federation with OIDC, see Configure Trust settings .

Step 5: Configure authentication

By default, when a federated user logs in, a new federated user is created in the CyberArk Cloud Directory. This occurs even if a user already exists in a source directory (CyberArk Cloud Directory, AD, LDAP, or Google) that has the same uuid or username.

To avoid duplicate identities, this feature maps the authenticated user to an existing user (if possible) before creating a new CyberArk Cloud Directory user with a Federated user type.

  1. Go to Authentication.

  2. Select Optional or Required in the Map federated user to existing directory user drop-down menu to enable the feature.

    Map federated users
    Map federated user to existing directory user setting Description

    Optional

    Selecting Optional means authentication of a mapped federation user results in the user of the mapped directory service. If a user cannot be mapped, a new federated user is created.

    Required

    Selecting Required means the user of a federation authenticates as the matching user of another directory service. If no match is found, login is denied. If Create cloud user if unable to map is also enabled, a matched CyberArk Cloud Directory user is created and login is permitted.

    Disabled (default)

    By default, when a federated user attempts to log in, login fails if a user with the same username exists in another directory service.

  3. (Optional) You may choose to map user attributes from the external IdP to CyberArk Identity attributes. To do this, enter the value that is sent as a claim from the IdP in the Federated user attribute to be mapped field. Examples of standard claims include Username, MobileNumber, Email, and DisplayName.

    The Federated user attribute to be mapped field is case-sensitive.

    If you choose to map an attribute, make sure you also select a Directory user attribute to be mapped.

  4. (Optional) Select a mapped directory service to search first for existing users.

    For the Name and UUID user mapping attributes, after the preferred directory service, the remaining directory services are searched according to their creation date. For all other attributes, only the mapped directory service is searched.

  5. (Optional) Select Update cloud users with federated user attributes to update a mapped CyberArk Cloud Directory user with the federated assertions.

Step 6: Configure routing rules

The routing rules determine when and how users are redirected to the external IdP for authentication, based on the federated domain and the user agent. To create a routing rule for the external IdP:

  1. Go to Routing Rules.

  2. Click Add to specify the federated domain. Users may include the domain name as part of their login credentials. The user is redirected to the external IdP based on the federated domain.

  3. Select the user agent from the drop-down menu to redirect the user to the external IdP for authentication. For example, if the federated domain is company.com and the User Agent is Browser, then the user is directed to the external IdP for authentication. In cases where the user agent does not match the routing rule, then the user is authenticated using RADIUS, Active Directory, or CyberArk Cloud Directory.

  4. Select the role from the drop-down menu to apply IdP authentication only for a subset of users. If you are using two or more external IdPs for the same domain, make sure that the user is only in one of the routing rules to avoid inconsistent behavior.

Make sure to configure an external IdP with at least one routing rule. If you specify a rule without any domain, then when the rule is met, all users except the super admin is redirected to the external IdP.