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.

  • A custom domain name can be up to 63 characters.

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. Verify that your custom domain name is resolvable before you continue.

    If your custom domain relies on public DNS, the exact custom domain name you configure, including any subdomain, must be resolvable. A correctly configured parent domain doesn’t guarantee that the subdomain resolves. For example, customers.mycompany.com could return a SERVFAIL DNS response, even though mycompany.com is configured correctly.

    Run the following dig command:

    dig @8.8.8.8 +short customers.mycompany.com

    Examine the command output:

    • If your custom domain name resolves, the command outputs the CNAME target, followed by the address records for the Advanced Identity Cloud tenant FQDN.

    • If your custom domain name doesn’t resolve, the command outputs nothing.

    To see the DNS response status, for example to confirm a SERVFAIL response, run:

    dig +noall +comments customers.mycompany.com

    Look for the status field in the header comment:

    • If the status is NOERROR, the query completed successfully.

    • If the status is SERVFAIL or NXDOMAIN, the query failed. Don’t proceed to add the custom domain until DNS resolution succeeds.

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

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

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

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

  7. 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 domains in your tenant environment share a Google-managed SSL certificate. Adding or updating a custom domain can cause Google to provision or reprovision this shared certificate. Provisioning typically completes within 30 minutes, but validation and activation can take up to 24 hours. During this period, your custom domains, including existing custom domains, can be inaccessible or reported as not secure.

      • Avoid making repeated changes to the custom domain configuration while provisioning is in progress, because each change can restart the process. If your custom domains are still inaccessible or reported as not secure 24 hours after you update the configuration, open a support case with Ping Identity support.

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

    • You don’t need to add the custom domain to the OAuth 2.0 provider’s Additional Audience Values setting for the end-user UI to work over your custom domain. That setting permits additional audience values when the provider verifies client authentication JWTs. It doesn’t affect redirect URIs. Add your custom-domain token endpoint to Additional Audience Values only if a client authenticates with a JWT whose aud claim references the custom domain. Learn more in JWT profile and authorization:oauth2-provider-settings.adoc#oauth-provider-additional-audience-values.

  8. 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. How long error messages display depends on the cause:

      • DNS propagation: the domain name doesn’t resolve, or the browser can’t connect. Wait for DNS changes to propagate. If error messages still display after 48 hours, make sure your Advanced Identity Cloud domain name settings are correct.

      • Certificate provisioning: the domain name resolves, but the browser reports the site as not secure. Allow up to 24 hours for Google to validate and activate the Google-managed SSL certificate. If your custom domain is still reported as not secure after 24 hours, open a support case with Ping Identity support.

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.