Use ESVs to override global configuration

Global configuration contains settings that apply to all realms in your Advanced Identity Cloud environment. Ping Identity manages this configuration on your behalf. However, several global configuration settings contain ESV placeholders set with default values. You can create the following ESV variables to override these default values in your environments to customize specific behaviors.

ESV name Possible values Default value Description

ESV name	Possible values	Default value	Description
`esv-am-nodes-certificatechain-validation-enforced`	Boolean	`false`	Lets you collect and validate all certificates in a certificate chain using the Certificate Collector and Certificate Validation nodes. To enable this behavior, set this ESV to `true`.
`esv-am-secrets-gsm-stableid-version-only`	Boolean	`true`	Lets you override the default `kid` value of the public key published in the JWK_URI. By default, the `kid` value indicates only the GSM secret version. Set this to `false` to include the name of the secret in the `kid`. Find more information in Override default `kid` values.
`esv-cts-use-etag-assertion-on-updates`	Boolean	`true`	Lets you use ETag assertions to verify that a CTS token hasn’t changed since the thread last read it. By default, parallel updates can no longer be made for CTS sessions. To re-enable previous behavior, set this ESV to `false`.
`esv-enable-oauth2-ignore-critical-headers`	Boolean	`false`	Lets you ignore critical headers in JWTs used in OAuth 2.0 flows. To enable this behavior, set this ESV to `true`.
`esv-enable-oauth2-sync-refresh-token-issuer`	Boolean	`true`	Lets you overwrite the `iss` claim of an introspectable server-side OAuth 2.0 token in the response from the `/oauth2/introspect` endpoint. To enable this behavior, set this ESV to `false`.
`esv-global-saml-error-page-http-binding`	String (`HTTP-POST` or `HTTP-Redirect`)	`HTTP-POST`	Lets you specify the HTTP binding used to redirect users to the SAML error page when an error occurs during a SAML 2.0 flow. To specify the HTTP binding, set this ESV to `HTTP-POST` or `HTTP-Redirect`.
`esv-global-saml-error-page-url`	String (URL)	`/saml2/jsp/saml2error.jsp`	Lets you specify the URL of the page that’s displayed to end users when an error occurs during a SAML 2.0 flow, for example, `https://mycompany.com/auth/saml-error-page.html`. Users are redirected to this page using the configured HTTP binding (`HTTP-POST` by default). You can change the HTTP binding by creating an ESV variable named `esv-global-saml-error-page-http-binding`.
`esv-global-saml-max-content-length`	Integer	`20480`	Lets you specify the maximum size, in bytes, for SAML requests. If a SAML request exceeds this size, it will be rejected. Learn more in this support KB article.
`esv-oauth2-grant-only-validated-scopes-on-refresh`	Boolean	`true`	Lets you disable scope validation script behavior that ensures refresh tokens only obtain access tokens with identical or narrower scopes. Setting this ESV to `false` re-enables the legacy behavior. Learn more in Scope validation.
`esv-oauth2-provider-request-object-processing-enforced`	Boolean	`false`	Lets you enforce certain validation rules when processing OAuth 2.0 request objects. To enable this behavior, set this ESV to `true`. Learn more in Request Object Processing Specification.
`esv-oauth2-request-object-restrictions-enforced`	Boolean	`false`	Lets you enforce stricter adherence to the PAR and JAR specifications. Setting the value to `true` enforces the authorization server to ignore authorize parameters outside the `request_uri`. Learn more in OAuth 2.0 endpoint parameters.
`esv-scripting-legacy-jwt-validation`	Boolean	`true`	Lets you disable legacy JWT validation behavior for OAuth 2.0 and OpenID Connect (OIDC) flows. If you require the non-legacy behavior, set this ESV to `false`.
`esv-scripting-legacynulloidcclaimsscriptbehaviour`	Boolean	`false`	If the OIDC Claims Plugin Type in the OAuth 2.0 provider is set to `SCRIPTED` but no script is selected, the `userinfo` endpoint returns the `sub` claim, in compliance with the OIDC specification. Previously, the `userinfo` endpoint returned an empty JSON object. If you still require this legacy behavior, set this ESV to `true`.

esv-am-nodes-certificatechain-validation-enforced

Boolean

false

Lets you collect and validate all certificates in a certificate chain using the Certificate Collector and Certificate Validation nodes. To enable this behavior, set this ESV to true.

esv-am-secrets-gsm-stableid-version-only

Boolean

true

Lets you override the default kid value of the public key published in the JWK_URI.

By default, the kid value indicates only the GSM secret version. Set this to false to include the name of the secret in the kid.

Find more information in Override default kid values.

esv-cts-use-etag-assertion-on-updates

Boolean

true

Lets you use ETag assertions to verify that a CTS token hasn’t changed since the thread last read it.

By default, parallel updates can no longer be made for CTS sessions. To re-enable previous behavior, set this ESV to false.

esv-enable-oauth2-ignore-critical-headers

Boolean

false

Lets you ignore critical headers in JWTs used in OAuth 2.0 flows. To enable this behavior, set this ESV to true.

esv-enable-oauth2-sync-refresh-token-issuer

Boolean

true

Lets you overwrite the iss claim of an introspectable server-side OAuth 2.0 token in the response from the /oauth2/introspect endpoint. To enable this behavior, set this ESV to false.

esv-global-saml-error-page-http-binding

String (HTTP-POST or HTTP-Redirect)

HTTP-POST

Lets you specify the HTTP binding used to redirect users to the SAML error page when an error occurs during a SAML 2.0 flow. To specify the HTTP binding, set this ESV to HTTP-POST or HTTP-Redirect.

esv-global-saml-error-page-url

String (URL)

/saml2/jsp/saml2error.jsp

Lets you specify the URL of the page that’s displayed to end users when an error occurs during a SAML 2.0 flow, for example, https://mycompany.com/auth/saml-error-page.html. Users are redirected to this page using the configured HTTP binding (HTTP-POST by default).

You can change the HTTP binding by creating an ESV variable named esv-global-saml-error-page-http-binding.

esv-global-saml-max-content-length

Integer

20480

Lets you specify the maximum size, in bytes, for SAML requests. If a SAML request exceeds this size, it will be rejected. Learn more in this support KB article.

esv-oauth2-grant-only-validated-scopes-on-refresh

Boolean

true

Lets you disable scope validation script behavior that ensures refresh tokens only obtain access tokens with identical or narrower scopes.

Setting this ESV to false re-enables the legacy behavior.

Learn more in Scope validation.

esv-oauth2-provider-request-object-processing-enforced

Boolean

false

Lets you enforce certain validation rules when processing OAuth 2.0 request objects. To enable this behavior, set this ESV to true. Learn more in Request Object Processing Specification.

esv-oauth2-request-object-restrictions-enforced

Boolean

false

Lets you enforce stricter adherence to the PAR and JAR specifications. Setting the value to true enforces the authorization server to ignore authorize parameters outside the request_uri. Learn more in OAuth 2.0 endpoint parameters.

esv-scripting-legacy-jwt-validation

Boolean

true

Lets you disable legacy JWT validation behavior for OAuth 2.0 and OpenID Connect (OIDC) flows. If you require the non-legacy behavior, set this ESV to false.

esv-scripting-legacynulloidcclaimsscriptbehaviour

Boolean

false

If the OIDC Claims Plugin Type in the OAuth 2.0 provider is set to SCRIPTED but no script is selected, the userinfo endpoint returns the sub claim, in compliance with the OIDC specification. Previously, the userinfo endpoint returned an empty JSON object. If you still require this legacy behavior, set this ESV to true.

PingOne Advanced Identity Cloud

Use ESVs to override global configuration