Custom Domains

Overview

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 forgerock.io 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
    https://openam-<your-company-name>.id.forgerock.io.

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

Add and verify a custom domain in Identity Cloud

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).
    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 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 absolute and relative URL paths will work.

        Examples:
  7. Next steps:

    • 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: https://id.mycompany.com.

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

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

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 URI 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 https://support.google.com/webmasters/answer/9008080?hl=en.