Identity Cloud

Custom domains


Configure a custom domain name when you want to use a customer-friendly URL to access Identity Cloud. You can use your own company name or brand, for example, in place of the default domain.

When choosing a custom domain name, consider the following:

  • 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 will continue to display the URL

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

    • Wrong:

    • Right:

  • 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

Before you begin, open a new browser window and sign in to the website for your domain name provider. For these steps, keep Identity Cloud open in a separate browser window.

  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 the domain name you want to use, then click Verify.
    The domain name must be unique, and must contain at least one period (dot).

    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 Host and Data information you’ll need to prove that you own the domain you’ve named.

  4. Create or modify your CNAME record.

    1. In a separate browser window, 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 now.

    3. In the CNAME record for your domain, copy and paste the Host and Data values provided in the Verify the Domain Ownership dialog box.

    4. Follow the domain name provider’s instructions to complete the operation.
      It may take up to 48 hours for the domain name changes to propagate.

  5. Return to the Verify the Domain Ownership dialog box. Click Verify.

  6. Configure the Base URL Source.

    1. Go to Native Access 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.

      After you’ve successfully configured your custom domain:

      • Identity Cloud generates the SSL certificates your domain needs.

      • 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 UI endUserUIClient redirect URIs.

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

        • For AM endpoint:
           you can use:

        • For IDM endpoint:
           you can use:

Verify a custom domain

  • It may take up to 48 hours for the 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.

  • 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. Example:

  • To test the hosted pages, use an incognito or private browser window to access an end-user URL. Example:

  • If error messages still display after 48 hours, make sure your Identity Cloud domain name settings are correct and match your CNAME record.

Promote custom domain placeholders

To prepare your Identity Cloud tenant to use a custom domain:

  1. Create an ESV variable, with the custom domain as the value.

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

    • If you have more than one custom domain, use a comma-separated list of custom domains; for example,

    • Create the same variable in the development, staging, and production tenant environments, using the value you want for each environment.

    Variables can be created using the following options:

  2. Submit an initial promotion request, referencing the ESV variable name. ForgeRock will insert a custom domain placeholder into the environment configuration and promote it to your development environment.

  3. Submit further promotion requests to promote the custom domain placeholder to your staging and production environments.

Once the custom domain placeholder has been promoted to all environments, changing the value of the custom domain ESV variable will trigger Identity Cloud to generate a new SSL certificate. This could result in downtime of up to 30 minutes.

Verify a custom domain in Google

If you use Google as a social login IDP, you will need to 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. This can be done through the Google Search Console. See

Access OIDC configuration discovery endpoint

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

Domain context Endpoint URL

Default ForgeRock domain

  • https://<tenant-name><realm>/.well-known/openid-configuration

Custom domain

  • Wrong:

  • Right:

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