PingOne Advanced Identity Cloud

Configure customer-friendly domain names

To let your end users access PingOne Advanced Identity Cloud through a customer-friendly URL, configure 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 Advanced Identity Cloud admin console 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.

Configure a custom domain

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

  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.

  3. In the Advanced Identity Cloud admin console, go to Realm > Realm Settings > Custom Domain.

  4. Click + Add a Custom Domain.

  5. In the Add a Custom Domain modal, enter your domain name. The domain name must be unique and must contain at least one period (dot). For example, id.mycompany.com.

  6. Click Next.

  7. In the Verify Domain Name Ownership modal:

    1. (Optional) Follow the on-screen instructions to set up a CNAME record.

    2. Click Verify, then click Done.

  8. Check the base URL source for the realm where the custom domain is to be used:

    1. Go to Native Consoles > Access Management.

    2. In 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, confirm that the Base URL Source option is set to Host/protocol from incoming request.

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

  10. 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, Advanced Identity Cloud generates a 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.

  11. 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:

      • 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, use an Incognito or private browser window to access an end-user URL. For example, access https://id.mycompany.com/login/?authIndexType=service&authIndexValue=<journey-name>#/.

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