Customize tenant URLs

This topic describes how to customize your tenant URL.

Custom domains or vanity URLs are not supported on Identity Security Platform (ISP) tenants. If you configure a custom domain or vanity URL you might experience a loss of functionality with ISP services, up to and including losing access to your tenant.

 

You have an ISP tenant if your tenant URL includes id.cyberark.cloud.

You have two methods to customize your tenant URL.

Tenant URL customization options

Method

Description

Add a custom subdomain

You can replace your tenant ID with a custom subdomain to create a vanity URL.

For example, if your tenant url is abc1234.my.idaptive.app, abc1234 is your tenant ID. Add a custom subdomain to create a URL such as mycompany.my.idaptive.app.

Add a custom domain

You can 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).

Add a custom subdomain

This section describes how to add a custom subdomain for your tenant.

  1. Go to Settings > Customization > Tenant URLs, then click Add Tenant URL.

  2. Enter a subdomain name, then click Save.

    DNS replication might take up to 20 minutes.

Add a custom domain

This section describes how to add a complete custom domain.

Before you begin

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

  • An allowlist that includes dns.google.com.

    When you use custom domains, an outgoing HTTPS call is made to dns.google.com to map the custom domain name to a CyberArk domain. Your organization needs to add the URL dns.google.com to an allowlist before you can sign in to the CyberArk Identity Browser Extension.

  • 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

PKCS12 command options
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, see 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

    PKCS12 command options
    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, see 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 Identity Administration portal.

To map your custom domain to CyberArk Identity root tenant URL:
  1. Sign in to the Identity Administration portal.

  2. Go to Settings > Customization > Tenant URLs, then click Add Custom Domain.

    You can add up to 10 custom domain URLs.

  3. Configure the following settings:

    Custom domain 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.
  4. 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.

Manage tenant URLs

This section describes how to set the default tenant URL, as well as modify custom domains or delete tenant URLs.

For customers on Identity Security Platform (ISP) tenants. Delete an existing custom URL to ensure full operational functionality.

You have an ISP tenant if your tenant URL includes id.cyberark.cloud.

Go to Settings > Customization > Tenant URLs and right click a custom tenant URL to see available management actions.

Action

Command

Description

Set the URL as the default URL.

Set as Default URL If selected as the default URL, users sign in to CyberArk Identity using the default URL.

Modify the custom domain.

Modify

Allows you to modify the custom domain settings, and check the expiration date of the SSL Server certificate and update it if necessary.

This action is only available for custom domains.

Delete the custom tenant URL.

Delete Deletes the URL entry. Users can no longer sign in to CyberArk Identity using the deleted URL.