Prepare CyberArk Trust Protection Foundation - Self-Hosted for SAML SSO

A secure SAML SSO process requires you provide the FQND (fully-qualified domain name) users enter to access CyberArk Trust Protection Foundation - Self-Hosted. Most organizations use multiple CyberArk Trust Protection Foundation - Self-Hosted servers to provide redundancy and load balancing. The server doesn't know the URL (of, for example, the load balancer) but the FQDN is required for secure communication between your Trust Protection Foundation server and the IDP. Use the following procedure to configure your FQDN in the web console.

To configure your FQDN in CyberArk Trust Protection Foundation - Self-Hosted

1. From the Platform menu bar, click Policy Tree.

2. Click the Platforms tree.

   You will be taken to the Platforms root, Platforms tab.

3. Click the Engine sub-tab.

4. In Trust Protection Foundation URL HostNames, locate Aperture (/Aperture), and enter the FQDN or IP address used to access CyberArk Trust Protection Foundation - Self-Hosted. The value you enter should match the FQDN found in the common name or DNS Subject Alternative Name of your CA-issued Venafi Operational Certificate so users don't encounter a certificate error.

   NOTE  Do NOT include the protocol (https://), or the /Aperture directory. Just enter the FQDN itself. So, if your Aperture URL is https://platform.venafi.com/Aperture, you would enter:

   platform.venafi.com

5. Click Save.

In CyberArk Trust Protection Foundation - Self-Hosted version 25.3, there is no support for just-in-time account creation, so you need to have CyberArk Trust Protection Foundation - Self-Hosted accounts for all users who will be logging in via the SAML identity provider as Active Directory (AD) or LDAP users.

It is important that your users are queryable by the value put in the NameID parameter of the Subject section of the SAML assertion. For example:

• For AD users, if the SAML IDP is using the e-mail address of the authenticated user as the NameID, then the CyberArk Trust Protection Foundation - Self-Hosted AD identity provider User Search properties should be configured to customize the user lookup to the email address. For details on customizing the user lookup to the email address, see Phase 1.3: Configure SAML user search expression.

• For LDAP users, if the SAML IDP is using the UPN (User Principle Name) of the authenticated user as the NameID, then the CyberArk Trust Protection Foundation - Self-Hosted LDAP identity driver User Search properties should be configured to add userPrincipalName (or whatever the corresponding attribute is in your LDAP directory) as described in Phase 1.3: Configure SAML user search expression.

  Whatever the attribute is, you want to follow these guidelines:

  • The attribute is something that the SAML IDP can provide.
  • The attribute is something that CyberArk Trust Protection Foundation - Self-Hosted has access to and can query against.
  • The attribute uniquely identifies one (and only one) user. If more than one user is returned in the query, authentication will fail an ambiguity security check.

Regardless of the identity provider, you need to export CyberArk Trust Protection Foundation - Self-Hosted data that you will use to connect to the identity provider.

The steps you need to take to configure Active Directory are in Creating an Active Directory connection. Complete AD configuration information can be found in Working with Active Directory

The steps you need to take to configure LDAP are in Creating an LDAP connection. Complete LDAP configuration information can be found in Working with LDAP and Oracle directory service.

When configuring a SAML-based identity provider configuration for logging in to CyberArk Trust Protection Foundation - Self-Hosted, you need to ensure the identity driver is configured to customize the user lookup to correctly and uniquely identify users.

You need to work with your identity management team to determine what type of unique identifier you are able to pass into the user assertion. We recommend using UPN, but you can use any unique attribute that is available to be put as the Name ID of the SAML assertion, and is available for query via your AD or LDAP connection.

To customize the user lookup in CyberArk Configuration Console

1. Use Remote Desktop to connect to the CyberArk Trust Protection Foundation - Self-Hosted host machine, and open the CyberArk Configuration Console.
2. Click the Connectors node.
3. Click the identity connector used by Active Directory.
4. In the actions panel, click Properties.

5. [Conditional] If necessary, log in to CyberArk Trust Protection Foundation - Self-Hosted as a master administrator.

   The next step depends on whether you are connecting with AD or LDAP.

   For Active Directory

   1. Click the User Search tab.
   2. Click Use Custom Expression.

   3. Change the value from:

      (&(ANR=$search$*)(objectCategory=$userclass$))

      to:

      (&(|(ANR=$search$)(userPrincipalName=$search$))(objectCategory=$userclass$))

      Unless your IDP is not sending the UPN of the user within the userID, in which case you should enter the following to search by e-mail address:

      (&(|(ANR=$search$)(mail=$search$))(objectCategory=$userclass$))

      TIP  Since this string uses the e-mail address of the user, and since an email address may not be unique in some systems, this is not the preferred option.

   4. Click OK.

   5. Open a command window, and reset IIS using the following command:

      iisreset

   For LDAP

   1. Click the Search Resolution tab.
   2. From Available Attributes, add both the following: ANR, and userPrincipalName.
   3. Click Add.
   4. Click OK to save.

   5. Open a command window, and reset IIS using the following command:

      iisreset

6. Log in to Aperture, and find an identity field, and verify that you can find one (and only one) user, searching with sample data that will be put in the Name ID of the SAML assertions.

   For example, if you're using UPN with Active Directory, log in as an AD user, and in a contact field search for a known email address in your organization (e.g. jane.doe@venafi.com) to make sure that one, and only one result is returned.

Now that you have configured the user lookup search expression, you're ready to move on to retrieving your Service Provider Metadata XML file.

In SAML authentication, the service provider (in this case CyberArk Trust Protection Foundation - Self-Hosted) publishes an XML metadata file, which is used for making the connection between the service provider and the identity provider. You need to export that file from CyberArk Configuration Console using the following procedure.

To retrieve the service provider metadata XML file

1. Use Remote Desktop to connect to your Trust Protection Foundation server, and open CyberArk Configuration Console.
2. Click the Authentication node.
3. Click the SAML component.
4. In the Actions panel, click Properties.
5. [Conditional] If requested, enter a master administrator username and password for CyberArk Trust Protection Foundation - Self-Hosted.

6. Select your IdP Vendor from the drop-down list.

   The settings window will populate based on your selection with the specific fields and terms for your identity provider.

   If you are using a non-tested IdP vendor, select Other, then enter the IdP name. This name will be used to identify the SAML configuration and for placing the certificate in the policy tree.

7. [Optional] Configure the Default Return URL. This is the default URL users will be taken to upon successful login through the SAML provider. Most organizations use aperture, as that is the most common starting place for users of the platform.

8. [Optional] Configure the Log out URL. If supported by your IdP, this is the URL that will trigger a log out of a session. As far as we know, Azure is the only tested IdP that supports a log-out URL.

   If your IdP does not support a Log out URL, and nothing is entered in this field, then CyberArk Trust Protection Foundation - Self-Hosted will not have a log-out option in the menu. After configuring this setting you need to restart IIS before you will see the change in the menu.

9. In the Export and import SAML metadata section, click Export service provider file and save the file to a location you'll be able to access during Phase 2.

   • Most identity providers can import the SP metadata XML file directly.
   • If your identity provider (including Okta) cannot import the SP metadata XML file, refer to the Service provider details for the URLs you will need when configuring your identity provider.