Create a custom domain for CyberArk Identity

This topic describes how to add your custom domain to CyberArk Identity and map it to the CyberArk root tenant URL. Using your own custom domain enables you to customize the user sign in experience to CyberArk Identity. For example, you can create the custom domain sso.example.com and map it to abc1234.my-idaptive.app (root tenant URL).

Prerequisites

Verify that you have the following prerequisites before mapping your custom domain to the CyberArk root tenant URL:

  • Existing custom domain

  • DNS CNAME record updated with the appropriate domain mapping (the custom domain mapped to the root tenant URL)

  • A .p12 or .pfx SSL certificate for your custom domain

    Certificates issued after September 1, 2020, must be valid for one year or less.

Convert a SSL certificate to the .p12/.pfx format

Creating a custom domain for CyberArk Identity requires a SSL certificate in the .p12/.pfx format. If you have an existing certificate in a different format (for example, .crt), you have to convert it to .p12/.pfx. Converting a certificate to .p12/.pfx requires the following:

  • the original private key

  • OpenSSL (included on macOS, available through Cywgin on Windows.

To convert an existing PEM certificate (for example, .crt) to the .p12/.pfx format

Open a Terminal window and run the following command:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

Option Description

openssl

The command to run OpenSSL.

pkcs12

Creates pkcs#12, also called .pfx files.
-export pkcs12 command option to create a new file, instead of parse an existing one.
-out pkcs12 command option to specify the filename for the new .pfx file. In this example command, the filename is certificate.pfx.

-inkey

pkcs12 command option to specify the file with the private key for the certificate. If you don't have the private key, a private key must be present in the input file. In this example command, the file with the private key is pirvateKey.key.

-in

pkcs12 command option to specify the filename to read certificates and private keys from. In this example command, the filename is certificate.crt.

For more information about changing certificate formats, refer to the OpenSSL pkcs12 man page.

  1. Download Cywgin and open the installer executable.

  2. Click Next to advance to the Choose a Download Source screen, then select Install from Internet and click Next.

  3. Click through the installation wizard until you reach the Select Packages screen, then type "openssl" in the search field.

  4. Navigate to All > Base and use the drop-down menu to select the latest version of openSSL, then click Next.

  5. Click through the installation wizard until you finish the installation, then open Cygwin64 Terminal and run the command openssl version to verify that you successfully installed OpenSSL.

    For example:

    $ openssl version
    OpenSSL 1.1.1f  31 Mar 2020
    
  6. In the Cygwin64 Terminal, run the following command.

    openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

    Option Description

    openssl

    The command to run OpenSSL.

    pkcs12

    Creates pkcs#12, also called .pfx files.
    -export pkcs12 command option to create a new file, instead of parse an existing one.
    -out pkcs12 command option to specify the filename for the new .pfx file. In this example command, the filename is certificate.pfx.

    -inkey

    pkcs12 command option to specify the file with the private key for the certificate. If you don't have the private key, a private key must be present in the input file. In this example command, the file with the private key is pirvateKey.key.

    -in

    pkcs12 command option to specify the filename to read certificates and private keys from. In this example command, the filename is certificate.crt.

    For more information about changing certificate formats, refer to the OpenSSL pkcs12 man page.

Map a custom domain to the root tenant URL

Once you have your custom domain and your DNS CNAME record updated with the appropriate mapping, you can configure the domain mapping in the CyberArk Identity Admin Portal.

To map your custom domain to the CyberArk Identity root tenant URL

  1. Log in to the Admin Portal.

  2. Click Settings > Customization > Tenant URLs.

  3. Click Add Custom Domain.

    You can add up to 10 custom domain URLs.

  4. Configure the following settings:

    Field

    Description

    Address

    This field is automatically populated with the CyberArk root tenant URL. You can use the content in this field for your DNS CNAME record mapping.

    Custom Domain

    Enter your existing custom domain name.

    SSL Server Certificate

    Click Upload to add the SSL Server certificate that corresponds to the custom domain name and enter the certificate password. The certificate filename should have an extension of .pfx or .p12.

    Certificates issued after September 1, 2020, must be valid for one year or less.

    It is important to keep track of the certificate expiration date and update it before the expiration date is reached. If the certificate expires before you update it, the website might not be reachable using the custom domain URL.
  5. Click Verify and Save and then click Close at the information message indicating the set up is complete.

    CyberArk Identity checks to make sure the certificate expiration date is within one year of the issue date (for certificates issued after September 1, 2020), the DNS points to CyberArk Identity, and the certificate domain name matches the name in the Custom Domain field.

Additional custom domain actions

Right-click a custom domain URL on the Tenant URLs page to access the following commands:

Command

Description

Set as Default URL If selected as the default URL, users sign in to CyberArk Identity using the default URL.
Modify Allows you to modify the custom domain settings, and check the expiration date of the SSL Server certificate and update it if necessary.
Delete Deletes the URL entry. Users can no longer sign in to CyberArk Identity using the deleted URL.