Federate with an external IdP using SAML

This topic describes how to add and configure an external IdP in the Identity Administration portal using SAML.

Add an external IdP

Step 1: Configure settings

1. Go to Settings > Users > External Identity Providers, then click Add.

2. Enter a unique IdP name.

3. Select Enable SHA256 for Signing Request to enable a signing request for your external IdP.

4. Click Add under Federation Domain to enter a unique domain name.

   This domain name is used as the login suffix for all external IdP users. It enables CyberArk to recognize users as coming from a specific IdP and redirects them accordingly. For example, you may want to use the IdP company name (for example, myCompany.com) as the domain name.

5. Click Add to add the domain name to the table.

Step 2: Configure group mappings

1. Click Group Mappings then Add to create a mapping of the group attribute values (for example, roles for other CyberArk tenants, or groups for IdPs using ADFS) to your groups.

2. Enter the partner role or ADFS group (ADFS federation) into the Group Attribute Value column, then either select an existing group in the Group Name column or enter a new name.

   This maps the IdP Roles/ADFS groups (information you should have received from the external IdP) to your groups. Each group needs to be a member of at least one role in your tenant. See Assign host groups to roles (Optional).

Step 3: Configure inbound metadata

Click Inbound Metadata to configure IdP settings using one of the following options:

Option	Description
Option 1	Upload the IdP configuration from URL. To use this option, paste the Identity Provider SAML Metadata URL provided by the external IdP.
Option 2	Upload the IdP configuration from a file. If your external IdP provided the identity provider SAML metadata in an XML file, you can upload it here.
Option 3	Manual Configuration. Manually enter the relevant information. This is not a recommended option.

Step 4: Configure outbound metadata

You can use the IdP metadata to send IdP configuration settings to your federating partner. Click Outbound Metadata to provide IdP configuration settings for your partners using one of the following options:

Option	Description
Option 1	Service Provider Metadata URL. Copy this link and paste at the external IdP SAML configuration.
Option 2	Download Service Provider Metadata. Upload this file at the IdP SAML configuration.
Option 3	Manual Configuration. Copy and paste this information at the IdP SAML configuration.

Step 5: Configure authentication

By default, when a federated user logs in, a new user is created in the CyberArk Cloud Directory, even if a user already exists in a source directory (CyberArk Cloud Directory, AD, LDAP, or Google) that has the same uuid or username. This feature maps the authenticated user to an existing user (if possible) before creating a new CyberArk Cloud Directory user. By default, assertions of the federated user are ignored in favor of the attributes of the mapped user.

1. Click Authentication to configure mapping federated users to existing directory users.

2. Select Enable URL redirecting if you want incoming federated users to be redirected to the target URL (as defined by the RelayState).

   If you enable URL redirecting, you can also limit redirection to a RelayState matching the URL pattern. If the field is empty, all URLs are allowed. The URL pattern is a wildcard pattern starting with https://. For example, https://www.example.com*.

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

   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 will authenticate 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	By default, when a federated user attempts to log in, login will fail if a user with the same username exists in another directory service.

4. (Optional) Enter a federated user mapping attribute.

   The default value is UserPrincipalName, because it is a required assertion.

   For AD and CyberArk Cloud Directory users, the federated user attribute mapping can be to any source directory attribute such as SSN or car license ID. For AD users, before mapping a federated user attribute to any AD attribute, you should replicate the user attribute in the Global Catalog. In the Active Directory schema, right-click on the user attribute, select Properties, then select the Replicate this attribute in the Global Catalog checkbox. For all other directory users, the federated user mapping attribute must be in the SAML assertion and map to either the Name or Uuid source directory attributes. If you change this value to an attribute that is not in the assertion and/or does not map to a unique attribute in a source directory, the login will fail.

5. Select a directory user mapping attribute.

6. (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.

7. (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.

Step 7: Configure attribute mapping

Once you add the external IdP provider, the Attribute Mapping tab appears when the Mapped Directory service is CyberArk Cloud Directory and you select any of the following checkboxes in the Authentication tab:

• Update cloud users with federated user attributes

• Create cloud user if unable to map

In the Attribute Mapping tab, you can dynamically map the federated user attributes to both the standard and additional attributes of CyberArk Cloud Directory.

Click Add to specify the attribute mapping and enter the following details:

Attribute	Description
Target Attribute	Select the target attribute (attribute name in CyberArk Cloud Directory) from the drop-down list.
Source Attribute	Enter the source attribute from the SAML federation to map it to the custom attribute in your application.

Assign host groups to roles (Optional)

For the host groups (those listed in the Group Name column of the Group Mappings tab) to have access to relevant applications and rights, you need to assign them to the relevant roles.

To assign the groups to roles:

1. Click Roles and select an existing role or create a new one.

2. Click Members, Add and search for the group.

   In the Source area, you must have the FDS user source selected to see the federated users/groups. Groups from federated services have the link icon/FDS label associated.

3. Select the group and click Add.
4. Click Save.

Map global group attributes (Optional)

You can create a mapping of global group attribute values (for example, roles for other Identity Administration tenants, or groups for partners using ADFS) for all your partners to your specified groups. If the system encounters conflicts, the individual group attribute mapping takes priority.

To map global group attributes to your specified groups:

1. Go to Settings > Users > External Identity Providers > Global Mappings.

2. Enter the global partner role or ADFS group (ADFS federation) into the Group Attribute Value text box, then either select an existing group in the Group Name text box or enter a new name.

   This maps global partner roles/ADFS groups (information you should have received from your partners) to your groups. Each group needs to be a member of at least one role in your tenant. See Assign host groups to roles (Optional).

3. Click OK.