PingOne Advanced Identity Cloud

Configure customer-friendly domain names

PingOne Advanced Identity Cloud lets you configure access to your tenant environments using one or more custom domains. Custom domains let you replace the default forgerock.io domain with a customer-friendly URL that reflects your company name or brand:

  • Configure the Alpha and Bravo realms to use a custom domain for hosted pages and your customer-facing applications.

  • Configure the top-level realm to use a custom domain for the admin console and your administrative applications.

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.

  • Don’t use your top-level domain name. This is because you must set up a CNAME record for each custom domain, but CNAME records aren’t permitted alongside other record types, including any A, NS, TXT, or SOA record types that belong to a top-level domain.

    • Wrong: mycompany.com

    • Right: id.mycompany.com

    Learn more in section 2.4 of RFC 1912.

Configure a custom domain

  1. Create a CNAME record with your DNS provider that points your custom domain to your Advanced Identity Cloud tenant environment’s FQDN. For example:

    Type Name Data

    CNAME

    customers.mycompany.com

    openam-mycompany.forgerock.io

  2. If your custom domain already has CAA records, add additional CAA records to ensure that Advanced Identity Cloud can generate Google-managed SSL certificates. Learn more in Specify the CAs that can issue your Google-managed certificate. For example:

    Type Name Data

    CAA

    customers.mycompany.com

    letsencrypt.org 0 issue

    CAA

    customers.mycompany.com

    pki.goog 0 issue

  3. Create a self-managed certificate.

    • This step is required if your custom domain relies on private DNS or you route your HTTP traffic through a WAF service.

    • This step is optional if your custom domain relies on public DNS.

  4. Add the custom domain to your realm. Learn more in:

  5. Configure the cookie domain for the custom domain using the instructions in Control cookie scope for custom domains.

  6. The custom domain should now be successfully configured:

    • If your custom domain relies on public DNS, and you don’t have a self-managed SSL certificate, Advanced Identity Cloud adds the custom domain to a Google-managed SSL certificate:

      • If this is the first custom domain you’ve added to any of the realms in your tenant, Advanced Identity Cloud creates a second Google-managed SSL certificate and adds the custom domain to the Subject Alternative Name (SAN) field of the certificate. It creates a second certificate so that the first Google-managed SSL certificate continues to serve the default tenant FQDN without interruption.

      • If this is the second or subsequent custom domain you’re adding to any realm in your tenant, Advanced Identity Cloud adds the custom domain to the SAN field of the second Google-managed SSL certificate.

    • The custom domain name is added to the realm settings.

    • The FQDN 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. Learn more in Configure OAuth clients.

  7. Confirm that the custom domain is working as expected:

    • To confirm that Advanced 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.

    • Confirm that URL paths work for both tenant domain and custom domain. You should be able to access the same resources using both domains.

      Example endpoints for the Alpha realm:

      • Access management:

        • https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate

        • https://<custom-domain-fqdn>/am/json/realms/root/realms/alpha/authenticate

      • Identity management:

        • https://<tenant-env-fqdn>/openidm/managed/alpha_user/<uuid>

        • https://<custom-domain-fqdn>/openidm/managed/alpha_user/<uuid>

      This doesn’t apply to the OIDC configuration discovery endpoint.

    • To test hosted pages or the Advanced Identity Cloud admin console, use an Incognito or private browser window:

      • If you added the custom domain to an Alpha or Bravo realm, access an end-user URL. For example:
        https://id.mycompany.com/login/?realm=/alpha#/.

      • If you added the custom domain to the top-level realm, access an administrator URL. For example:
        https://id.mycompany.com/login/?realm=/#/.

    • If your custom domain relies on public DNS, it can 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 might display until the changes take effect. If error messages still display after 48 hours, make sure your Advanced Identity Cloud domain name settings are correct.

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, learn more in 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 domain

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

Custom domain

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

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

Using the incorrect endpoint URL can result in an OIDC discovery failure due to an issuer mismatch.