PingOne Advanced Identity Cloud

Configure customer-friendly domain names

Access PingOne Advanced Identity Cloud through a customer-friendly URL by configuring a custom domain name. For example, replace the default forgerock.io domain with your own company name or brand.

Consider the following points when you customize a domain name:

  • You can set a custom domain name only at the realm level.

  • You can set multiple custom domain names per realm.

  • The Advanced Identity Cloud admin console continues to display the default tenant environment URL.

  • Don’t use your top-level domain name. This is because you must set up a CNAME record for each custom domain, but CNAME records aren’t permitted alongside other record types, including any A, NS, TXT, or SOA record types that belong to a top-level domain.

    • Wrong: mycompany.com

    • Right: id.mycompany.com

    Learn more in section 2.4 of RFC 1912.

  • Changing your custom domain name affects your end-user UIs and REST APIs.

Set up a custom domain in Advanced Identity Cloud

Configure a custom domain using the admin console

  1. Choose one of these options:

  2. In the Advanced Identity Cloud admin console, go to Realm > Realm Settings > Custom Domain.

  3. Click + Add a Custom Domain.

  4. In the Add a Custom Domain dialog box, enter your domain name, then click Next.
    The domain name must be unique, and must contain at least one period (dot).
    Example: id.mycompany.com.

  5. Choose one of these options:

    • If your custom domain relies on public DNS:

      1. In the Verify Domain Name Ownership dialog box, Advanced Identity Cloud provides the Host and Data information that you’ll use in the next step to prove that you own the domain you’ve named.

      2. Create a CNAME record with your domain name registrar.

      3. Return to the Verify the Domain Ownership dialog box, and click Verify.

    • If your custom domain relies on private DNS or you route your HTTP traffic through a WAF service:

      1. In the Verify Domain Name Ownership dialog box, click Verify.

  6. Configure the base URL source for the realm where the custom domain is to be used.

  7. The custom domain should now be successfully configured:

    • If your custom domain relies on public DNS and you do not have a self-managed SSL certificate, Advanced Identity Cloud generates a Google-managed SSL certificate.

      If your custom domain already has CAA records, you must add additional CAA records to ensure that Advanced Identity Cloud can generate Google-managed SSL certificates. Learn more in Specify the CAs that can issue your Google-managed certificate.

    • The custom domain name is added to the realm settings.

    • The FDQN for your custom domain name is mapped to server defaults.

    • The custom domain name is added to the Redirection URIs field of the end-user-ui OAuth 2.0 client. Learn more in Configure OAuth clients.

    • Both tenant domain and custom domain URL paths work; however, this does not apply to the OIDC configuration discovery endpoint.

      Examples:

      • For AM endpoint:
         https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate
         you can use:
         https://id.mycompany.com/am/json/realms/root/realms/alpha/authenticate

      • For IDM endpoint:
         https://<tenant-env-fqdn>/openidm/managed/alpha_user/<uuid>
         you can use:
         https://id.mycompany.com/openidm/managed/alpha_user/<uuid>

  8. Confirm that the custom domain is working as expected. Learn more in Check that a custom domain is working in your browser.

Configure a custom domain using ESVs

The option to configure a custom domain using ESVs has been removed from Advanced Identity Cloud. Instead, you can Configure a custom domain using the admin console in any environment without needing to configure ESVs and promote configuration.

If you previously used ESVs to configure a custom domain, the ESV values have been migrated to normal UI input values and the custom domain still works as normal.

Add a CNAME record to your custom domain

If your custom domain relies on public DNS, add a CNAME record to it so Advanced Identity Cloud can validate that you are the domain owner.

  1. Sign in to the website for your domain name registrar.

  2. Find the CNAME record for your domain. If you don’t already have a CNAME record for your domain, then follow the domain name provider’s instructions to create one.

  3. In the CNAME record for your domain, enter the following values to create an alias from your custom domain to your Advanced Identity Cloud tenant domain:

    • In the host field, enter your custom domain FQDN; for example, id.mycompany.com.

    • In the data field, enter your Advanced Identity Cloud tenant FQDN; for example, openam-mycompany.forgerock.io.

  4. Follow the domain name provider’s instructions to complete the operation.

  5. It may take up to 48 hours for domain name changes to propagate. Learn more in Check when CNAME domain name changes propagate.

Check when CNAME domain name changes propagate

If you add a CNAME record to your custom domain, you can use the following ways to check when the changes propagate:

  • Use a DNS checker website; for example https://dnschecker.org/all-dns-records-of-domain.php.

  • Use the nslookup command-line tool:

    If you do not have nslookup installed, refer to https://command-not-found.com/nslookup to find installation instructions for your particular package manager. 
    $ nslookup -q=cname id.mycompany.com(1)
Server:     fe80::ced4:2eff:fec3:40e%8
Address:    fe80::ced4:2eff:fec3:40e%8#53
id.mycompany.com     canonical name = openam-mycompany.forgeblocks.com.(2)
    1 Replace id.mycompany.com with your custom domain FQDN.
    2 The output shows that the domain id.mycompany.com is an alias for the canonical name openam-mycompany.forgeblocks.com.

Deactivate CNAME record verification for your custom domain

If your custom domain relies on private DNS, or you route your HTTP traffic through a WAF service, open a support case to deactivate CNAME record verification.

  1. Go to https://support.pingidentity.com.

  2. Click Create a case.

  3. Follow the steps in the case submission wizard by selecting your account and contract and answering questions about your tenant environments.

  4. On the Please answer the following questions to help us understand the issue you’re facing page, enter the following details, and then click Next:

    Field Value

    What product family is experiencing the issue?

    Select PingOne Advanced Identity Cloud

    What specific product is experiencing the issue?

    Select Tenant Settings

    What version of the product are you using?

    Select NA

    Which component is affected?

    Select Custom Domains

  5. On the Tell us about the issue page, enter the following details, and then click Next:

    Field Value

    Provide a descriptive title for your issue

    Enter Disable CNAME record verification for a custom domain.

    Describe the issue below

    Enter your custom domain FQDN.

  6. Click Submit.

Configure the base URL source for a realm to support a custom domain

To support HTTP requests from a custom domain, the base URL source of the associated realm needs to be configured to retrieve the hostname, the server name, and the port number from incoming HTTP requests.

  1. Go to Native Consoles > Access Management.

  2. From the Realms menu, choose the realm that contains the custom domain name.

  3. On the Services page, click Base URL Source to edit its configuration.

  4. On the Base URL Source page, change the Base URL Source option to
    Host/protocol from incoming request.

  5. Click Save Changes.

Check that a custom domain is working in your browser

  • To confirm that Advanced Identity Cloud is serving traffic over HTTPS (TLS) for your custom domain name, in a browser, go to your custom domain location. For example, go to https://id.mycompany.com.

  • To test hosted pages, use an incognito or private browser window to access an end-user URL. For example, access https://id.mycompany.com/login/?authIndexType=service&authIndexValue=mytreename#/.

  • If your custom domain relies on public DNS, it may take up to 48 hours for domain name changes to propagate. If you try to use the new domain name to access your website, error messages may display until the changes take effect. If error messages still display after 48 hours, make sure your Advanced Identity Cloud domain name settings are correct and match your CNAME record. Learn more in Check when CNAME domain name changes propagate.

Verify a custom domain in Google

If you use Google as a social login IDP, you must use your domain to configure the redirect URL fields of your OAuth 2.0 apps. This might create prompts from Google to verify your domain with your domain provider. For information about how to verify your domain, learn more in Verify your site ownership on the Google Search Console.

Access OIDC configuration discovery endpoint

When you configure a custom domain, the OIDC configuration discovery endpoint URL changes:

Domain context Endpoint URL

Default domain

  • https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/<realm>/.well-known/openid-configuration

Custom domain

  • Incorrect:
    https://<custom-domain-fqdn>/am/oauth2/realms/root/realms/<realm>/.well-known/openid-configuration

  • Correct:
    https://<custom-domain-fqdn>/.well-known/openid-configuration

Using the incorrect endpoint URL can result in an OIDC discovery failure due to an issuer mismatch.

Learn more in Control cookie scope for custom domains.