Identity Cloud

Custom domains

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

  1. Choose one of these options:

  2. In the Identity Cloud admin UI, 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, 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, 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

The option to configure a custom domain using ESVs has been removed from Identity Cloud. Instead, you can Configure a custom domain using the UI 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 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. Open a How-To ticket with ForgeRock Support.

  2. On the How Do I...? page, provide values for the following fields:

    Field Value

    Product

    Select the following from the lists:

    • ForgeRock Identity Cloud

    • Tenant Settings

    • Realms - Custom Domains

    What are you trying to achieve?

    Enter "Disable CNAME record verification for a custom domain".

    Please provide a short description

    Enter your custom domain FQDN.

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

You can configure the cookie domain in Identity Cloud to control which applications have access to the cookies you create.

Identity Cloud supports two cookie domain configurations:

Custom domain level

The cookie domain matches the custom domain; for example, for the custom domain id.mycompany.co.uk, the cookie domain would also be id.mycompany.co.uk.

You may need to use the custom domain level to ensure that a session cookie can only be set or modified by applications running on a single subdomain (for example, sso.mycompany.co.uk).

Custom domain level configuration is enabled by default if your tenant environments were created on or after June 17, 2022.
Domain level

The cookie domain is determined from the custom domain using eTLD+1; for example, for the custom domain id.mycompany.co.uk, the cookie domain would be mycompany.co.uk as the eTLD is .co.uk and therefore the eTLD+1 is mycompany.co.uk.

You may need to use the domain level for the following reasons:

  • You want to set a session cookie on one subdomain (for example, sso.mycompany.co.uk) but make it available to an application running on a different subdomain (for example, banking.mycompany.co.uk).

  • You want to set a shadow session cookie at the domain level (for example, mycompany.co.uk) to make it available to legacy applications that are yet to be migrated to Identity Cloud.

Domain level configuration is enabled by default if your tenant environments were created before June 17, 2022.

To change the cookie domain configuration, raise a support ticket:

  1. Go to ForgeRock Support, and click ForgeRock Identity Cloud.

  2. Click Identity Cloud: Config Request from the ForgeRock Identity Cloud options.

  3. In the Request Type section, provide values for the following fields:

    Field Value

    Hostname(s)

    Enter a comma-separated list of FQDNs for your sandbox[1], development, UAT[2], staging, and production tenant environments.

    What would you like to do?

    Select Change cookie domain configuration.

    Do you give permission for ForgeRock to access and make changes to your environment?

    Select Yes to allow ForgeRock Support to access your environments.

  4. In the Cookie domain configuration section, provide a value for the following field:

    Field Value

    What level do you want the cookie domain to be?

    Select Custom domain level or Domain level.

    To determine the default setting for your tenant environments, refer to Supported cookie domain configurations.

  5. Click Submit to create the support ticket.

  6. ForgeRock support confirms when the configuration has been changed.

Copyright © 2010-2024 ForgeRock, all rights reserved.