PingOne

Custom domain impacts and migration considerations

When you add a custom domain to a PingOne environment, the environment has two sets of URLs:

  • Standard PingOne URLs

  • Custom domain URLs

Both sets are valid and functional.

How a custom domain changes your environment

Adding a custom domain affects how PingOne identifies itself to applications and identity providers (IdPs) in the following ways:

Token issuer changes: Both the OpenID Connect (OIDC) and SAML issuer defaults to the custom domain. PingOne accepts both the standard and custom domain issuer, but your configuration should be consistent. Use one or the other for a given integration, not a mix of both.

  • URL path structure: Custom domain URLs omit the envId path segment that standard URLs include:

    • Standard URL: https://auth.pingone.<region>/<envId>/as

    • Custom domain URL: https://<customDomain>/as

Endpoint mapping reference

The following table shows how standard PingOne URLs map to custom domain URLs across supported protocols. Assume [.codeph]<customDomain> is your configured domain (for example, sso.example.com).

Protocol Purpose Standard URL Custom domain URL

OIDC app

Issuer

https://auth.pingone.<region>/<envId>/as

https://<customDomain>/as

OIDC app

Token endpoint

https://auth.pingone.<region>/<envId>/as/token

https://<customDomain>/as/token

SAML app

Issuer ID

https://auth.pingone.<region>/<envId>

https://<customDomain>

SAML app

Initiate single sign-on URL

https://auth.pingone.<region>/<envId>/saml20/idp/startsso?spEntityId=<partnerEntityId>

https://<customDomain>/saml20/idp/startsso?spEntityId=<partnerEntityId>

Microsoft 365 app

IssuerUri

https://auth.pingone.<region>/<envId>/applications/<appId>

https://<customDomain>/applications/<appId>

Microsoft 365 app

PassiveSignInUri

https://auth.pingone.<region>/<envId>/wsf/prp/<appId>

https://<customDomain>/wsf/prp/<appId>

External IdP (SAML)

ACS Endpoint

https://auth.pingone.<region>/<envId>/saml20/sp/acs

https://<customDomain>/saml20/sp/acs

External IdP (SAML)

SingleLogoutService

https://auth.pingone.<region>/<envId>/saml20/sp/slo

https://<customDomain>/saml20/sp/slo

External IdP (OIDC)

Callback URL

https://auth.pingone.<region>/<envId>/rp/callback/openid_connect

https://<customDomain>/rp/callback/openid_connect

The PingOne (SP) Entity ID for external SAML IdPs https://auth.pingone.<region>/<uuid> is generated by PingOne and doesn’t have a custom domain equivalent. Leave this value unchanged.

You can view the custom domain and standard URL versions of these endpoints on the Overview tab for the application. Learn more in Viewing application details.

API and CORS guidance

Not all PingOne API host names support custom domains. You can find a complete list of host names that support them in Custom Domains in the PingOne API documentation.

CORS for single-page applications (SPAs): If you’re integrating PingOne Auth APIs with your own hosted single-page applications, cross-origin resource sharing (CORS) is typically handled automatically through the Allowed Origins configured in your PingOne application settings. PingOne DaVinci doesn’t have a separate CORS configuration. It uses the allow lists defined in PingOne applications.

  • New integrations: When you add new applications or IdPs after configuring a custom domain, use the custom domain URLs. This avoids the need for a migration later.

Transitioning existing integrations

When you add a custom domain to an environment that already has configured applications or IdPs, you don’t need to update these integrations to use the custom domain URLs immediately. The standard PingOne URLs remain valid.

If your custom domain routes through Cloudflare (either because it was migrated or created after Cloudflare was implemented), use custom domain URLs to take advantage of additional security features, such as inbound traffic policies. Learn more in Migrating a custom domain to Cloudflare.

Changing the Issuer, Issuer ID, IssuerUri, or ACS URLs for an existing integration is a breaking change. You must coordinate with your service provider or IdP partners to update their metadata and trust settings before making the switch. Both sides must update at the same time to avoid authentication failures.