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

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 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 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, and click Verify.

  6. Configure the Base URL Source.

    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.

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

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. 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 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 API naming convention. For example, use esv-customdomain or esv-customdomain-alpha.

    • If you have one custom domain, use a string for the ESV value. For example, use id-customers.company.com.

    • If you have more than one custom domain, use a comma-separated list for the ESV value. For example, use id-staff.company.com,id-customers.company.com.

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

    Create ESV variables in the following ways:

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

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

After 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 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-2022 ForgeRock, all rights reserved.