Identity Cloud

Custom domains

Overview

Access 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 Identity Cloud admin UI continues to display the default tenant environment URL.

  • Don’t use your top-level domain name.

    • Wrong: mycompany.com

    • Right: id.mycompany.com

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

Set up a custom domain in Identity Cloud

Configure a custom domain using the UI

The UI lets you set up a custom domain in an individual environment for testing purposes. However, it is not currently compatible with the configuration promotion process. When you are satisfied that the custom domain works as expected within an environment, you need to set it as an ESV. Refer to Configure a custom domain using ESVs.
If your custom domain relies on private DNS or you route your HTTP traffic through a WAF service, you can’t use the UI to set up your custom domain. Instead, you must use an ESV. Refer to Configure a custom domain using ESVs.
  1. In the Identity Cloud admin UI, go to Realm > Realm Settings > Custom Domain.

  2. Click + Add a Custom Domain.

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

    After Identity Cloud validates your domain name, you’re prompted to verify your domain name ownership. In the Verify Domain Name Ownership dialog box, 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.

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

  5. Return to the Verify the Domain Ownership dialog box, and 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, 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 Identity Cloud can generate Google-managed SSL certificates. Refer to 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. Refer to 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. Refer to Check that a custom domain is working in your browser.

Configure a custom domain using ESVs

  1. Choose one of the options below to configure your domain:

  2. In your development environment:

    1. Create an ESV variable with the type as an array:

      • When naming the variable, follow the ESV API naming convention; for example, esv-customdomain or esv-customdomain-alpha.

      • If you have no custom domain for the environment, use an empty array for the ESV value.

      • If you have one custom domain for the environment, use a single-item array for the ESV value; for example, ["id-customers.company.com"].

      • If you have more than one custom domain for the environment, use a multi-item array for the ESV value; for example, ["id-staff.company.com","id-customers.company.com"].

        Create ESV variables in the following ways:

    2. Raise a support ticket to insert a configuration placeholder into your development environment configuration for the custom domain ESV you created in step 2a:

      1. Go to the Backstage website, and click Support > Tickets.

      2. On the support tickets page, click New Ticket.

      3. On the New Ticket page, choose How Do I…​?.

      4. Provide values for the following fields:

        Section Field Value

        Product

        Product

        1. ForgeRock Identity Cloud

        2. Configuration

        Details

        What are you trying to achieve?

        Add a placeholder into development configuration for a custom domain ESV

        Please provide a short description

        Enter the ESV name and the realm the custom domain applies to.

      5. Click Submit.

      6. Wait until the support ticket is resolved before moving to the next step.

    3. If you added a custom domain to the custom domain ESV for this environment:

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

      2. 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, 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 Identity Cloud can generate Google-managed SSL certificates. Refer to 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. Refer to 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>

      3. Confirm that the custom domain is working as expected. Refer to Check that a custom domain is working in your browser.

  3. In your staging environment:

    1. Repeat step 2a for your staging environment. Ensure that the ESV name is the same as you set up in the development environment.

    2. Run a promotion to move the configuration change from your development environment to your staging environment. Refer to:

    3. Repeat step 2c for your staging environment.

  4. In your production environment:

    1. Repeat step 2a for your production environment. Ensure that the ESV name is the same as you set up in the development environment.

    2. Run a further promotion to move the configuration change from your staging environment to your production environment.

    3. Repeat step 2c for your production environment.

If your custom domain relies on a Google-managed SSL certificate, changing the value of the custom domain ESV variable will trigger Identity Cloud to generate a new Google-managed SSL certificate. As a result, you may not be able to access your tenant using the custom domain for up to 30 minutes.

Add a new custom domain to an ESV

  1. Configure your new custom domain following the instructions in step 1 of Configure a custom domain using ESVs.

  2. In your development, staging, or production environment:

    1. Add the new custom domain to the ESV array value following the instructions in step 2a of Configure a custom domain using ESVs.

    2. Restart Identity Cloud services following the instructions in Update an ESV referenced by a configuration placeholder.

    3. Complete configuration following the instructions in step 2c of Configure a custom domain using ESVs.

If your custom domain relies on a Google-managed SSL certificate, ForgeRock recommends that you only add one new custom domain at a time to minimize the risk to existing custom domains from any new certificate configuration errors.

Switch a custom domain using an ESV

  1. Configure your new custom domain following the instructions in step 1 of Configure a custom domain using ESVs.

  2. In your development, staging, or production environment:

    1. Replace the existing custom domain with the new custom domain as the ESV array value following the instructions in step 2a of Configure a custom domain using ESVs.

    2. Restart Identity Cloud services following the instructions in Update an ESV referenced by a configuration placeholder.

    3. Complete configuration following the instructions in step 2c of Configure a custom domain using ESVs.

Add a CNAME record to your custom domain

If your custom domain relies on public DNS, add a CNAME record to it so 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 Identity Cloud tenant domain:

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

    • In the data field, enter your 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. Refer to 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, raise a ticket to deactivate CNAME record verification.

  1. Go to the Backstage website, and click Support > Tickets.

  2. On the support tickets page, click New Ticket.

  3. On the New Ticket page, choose How Do I…​?.

  4. Provide values for the following fields:

    Section Field Value

    Product

    Product

    1. ForgeRock Identity Cloud

    2. DNS

    Details

    What are you trying to achieve?

    Disable CNAME record verification for a custom domain

    Please provide a short description

    Enter custom domain FQDN

  5. 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 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 Identity Cloud domain name settings are correct and match your CNAME record. Refer to 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, refer to 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 ForgeRock domain

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

Custom domain

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

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

Using the wrong endpoint URL can result in an OIDC discovery failure due to an issuer mismatch.
Copyright © 2010-2023 ForgeRock, all rights reserved.