--- title: ClientRegistration description: Configure ClientRegistration to hold OAuth 2.0 and OpenID Connect client credentials, issuer reference, scopes, and secrets for PingGateway component: pinggateway version: 2024.11 page_id: pinggateway:reference:ClientRegistration canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ClientRegistration.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-06-02T09:47:34Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/ClientRegistration.html section_ids: ClientRegistration-usage: Usage ClientRegistration-properties: Properties ClientRegistration-clientId: clientId ClientRegistration-issuer: issuer ClientRegistration-pkceMethod: pkceMethod ClientRegistration-scopes: scopes ClientRegistration-registrationHandler: registrationHandler ClientRegistration-authenticatedRegistrationHandler: authenticatedRegistrationHandler ClientRegistration-clientSecretUsage: clientSecretUsage ClientRegistration-clientSecretId: clientSecretId ClientRegistration-secretsProvider: secretsProvider ClientRegistration-skipSignatureVerification: skipSignatureVerification ClientRegistration-jwtExpirationTimeout: jwtExpirationTimeout (deprecated) ClientRegistration-privateKeyJwtSecretId: privateKeyJwtSecretId (deprecated) ClientRegistration-tokenEndpointAuthMethod: tokenEndpointAuthMethod (deprecated) ClientRegistration-tokenEndpointAuthSigningAlg: tokenEndpointAuthSigningAlg (deprecated) ClientRegistration-example: Example ClientRegistration-moreinfo: More information --- # ClientRegistration A ClientRegistration holds information about registration with an OAuth 2.0 Authorization Server or OpenID Provider. The configuration includes the client credentials that are used to authenticate to the identity provider. The client credentials can be included directly in the configuration, or retrieved in some other way using an expression, described in [Expressions](Expressions.html#Expressions). ## Usage ```none { "name": string, "type": "ClientRegistration", "config": { "clientId": configuration expression, "issuer": Issuer reference, "pkceMethod": configuration expression, "scopes": [ configuration expression, …​], "registrationHandler": Handler reference, "authenticatedRegistrationHandler": Handler reference, "clientSecretUsage": configuration expression, "clientSecretId": configuration expression, "secretsProvider": SecretsProvider reference, "skipSignatureVerification": configuration expression, "jwtExpirationTimeout": duration, //deprecated "privateKeyJwtSecretId": configuration expression, //deprecated "tokenEndpointAuthMethod": enumeration, //deprecated "tokenEndpointAuthSigningAlg": string //deprecated } } ``` ## Properties ### clientId `"clientId"`: *configuration expression<[string](preface.html#definition-string)>, required* The `client_id` obtained when registering with the Authorization Server. [Expressions](Expressions.html) describes alternatives to setting this to a literal string. When using a login page with an [AuthorizationCodeOAuth2ClientFilter](AuthorizationCodeOAuth2ClientFilter.html), the link to the `/login` endpoint must refer to a valid `clientId` identified by this property. ### issuer `"issuer"`: *Issuer [reference](preface.html#definition-reference), required* The provider configuration to use for this client registration. Provide the name of an [Issuer](Issuer.html) defined in the heap or an inline Issuer configuration object. ### pkceMethod `"pkceMethod"`: *configuration expression<[string](preface.html#definition-string)>, optional* The [Proof Key for Code Exchange (PKCE)](https://www.rfc-editor.org/rfc/rfc7636.html) code challenge method; one of: * `S256`: Use a SHA256-based encoding of the code verifier. * `none`: Disable PKCE. Default: `S256` ### scopes `"scopes"`: *array of configuration expression<[strings](preface.html#definition-string)>, optional* Array of scope strings to present to the user for approval and to include in tokens for decisions about access to protected resources. Default: Empty ### registrationHandler `"registrationHandler"`: *Handler [reference](preface.html#definition-reference), optional* HTTP client handler to invoke during client registration, to access endpoints that don't require client authentication. Provide either the name of a [Handler](Handlers.html) defined in the heap or an inline Handler configuration object. Usually set this to the name of a [ClientHandler](ClientHandler.html) configured in the heap or a [Chain](Chain.html) that ends in a ClientHandler. Default: [ClientHandler](ClientHandler.html) ### authenticatedRegistrationHandler `"authenticatedRegistrationHandler"`: *Handler [reference](preface.html#definition-reference), optional* HTTP client handler to invoke during client registration to access endpoints that require client authentication. Configure this property as a [Chain](Chain.html) with one of the following filters for client authentication: * [ClientSecretBasicAuthenticationFilter](ClientSecretBasicAuthenticationFilter.html) * [ClientSecretPostAuthenticationFilter](ClientSecretPostAuthenticationFilter.html) * [EncryptedPrivateKeyJwtClientAuthenticationFilter](EncryptedPrivateKeyJwtClientAuthenticationFilter.html) * [PrivateKeyJwtClientAuthenticationFilter](PrivateKeyJwtClientAuthenticationFilter.html) For example: ```json { "name": "AuthenticatedRegistrationHandler", "type": "Chain", "config": { "handler": "ForgeRockClientHandler", "filters": [ { "type": "ClientSecretBasicAuthenticationFilter", "config": { "clientId": "service-client", "clientSecretId": "client.secret.id", "secretsProvider" : "SystemAndEnvSecretStore-1" } } ] } } ``` Default: `registrationHandler` with no authentication filter ### clientSecretUsage `"clientSecretUsage"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Specifies how to use the `"clientSecretId"`; one of: * `CLIENT_AUTHENTICATION_ONLY` * `ID_TOKEN_VALIDATION_AND_CLIENT_AUTHENTICATION` * `ID_TOKEN_VALIDATION_ONLY` Default: `CLIENT_AUTHENTICATION_ONLY` ### clientSecretId `"clientSecretId"`: *configuration expression\, required to verify ID tokens with HMAC-based signatures* The secret ID of the client secret. Set this for ID token validation when the OpenID provider signs ID tokens using an HMAC algorithm. In addition, set `"clientSecretUsage"` to `ID_TOKEN_VALIDATION_AND_CLIENT_AUTHENTICATION` or `ID_TOKEN_VALIDATION_ONLY` and use a `"secretsProvider"` to access the client secret. This secret ID must point to a [GenericSecret](../security-guide/keys.html#secret-types). ### secretsProvider `"secretsProvider"`: *SecretsProvider reference, required to verify ID tokens with HMAC-based signatures* The [SecretsProvider](SecretsProvider.html) to query for the client's [GenericSecret](../security-guide/keys.html#secret-types). When the OpenID provider signs ID tokens using an HMAC algorithm, use this provider to access the `"clientSecretId"`. ### skipSignatureVerification `"skipSignatureVerification"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* A flag for signature validation of OpenID Connect ID tokens: * `true`: Don't validate signatures. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For backward compatibility, the default value of this property is `true`.Before using the value `true`, consider the security impact on your deployment. Use only when the connection between the Issuer and Client is direct and well secured. | * `false`: Validate signatures. Default: `true` ### jwtExpirationTimeout (deprecated) `"jwtExpirationTimeout"`: *duration, optional* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated. Use [authenticatedRegistrationHandler](#ClientRegistration-authenticatedRegistrationHandler) instead. Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | When `private_key_jwt` is used for authentication, this property specifies the duration for which the JWT is valid. Default: 1 minute ### privateKeyJwtSecretId (deprecated) `"privateKeyJwtSecretId"`: *configuration expression\, required when `private_key_jwt` is used for client authentication* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated. Use [authenticatedRegistrationHandler](#ClientRegistration-authenticatedRegistrationHandler) instead. Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The secret ID of the key to sign the JWT. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). ### tokenEndpointAuthMethod (deprecated) `"tokenEndpointAuthMethod"`: *enumeration, optional* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated. Use [authenticatedRegistrationHandler](#ClientRegistration-authenticatedRegistrationHandler) instead. Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The authentication method with which a client authenticates to the Authorization Server or OpenID provider at the token endpoint. Learn more in the OpenID documentation on [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication). The following client authentication methods are allowed: * `client_secret_basic`: Clients that have received a `client_secret` value from the Authorization Server authenticate with the Authorization Server with the HTTP Basic authentication scheme: ```http POST /oauth2/token HTTP/1.1 Host: as.example.com Authorization: Basic .... Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=... ``` * `client_secret_post`: Clients that have received a `client_secret` value from the Authorization Server authenticate with the Authorization Server with the client credentials in the request body: ```http POST /oauth2/token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&; client_id=...& client_secret=...& code=... ``` * `private_key_jwt`: Clients send a signed JSON Web Token (JWT) to the Authorization Server. PingGateway builds and signs the JWT and prepares the request: ```http POST /token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=...& client_id=& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWxwOl ... ZT ``` If the Authorization Server doesn't support `private_key_jwt`, the dynamic registration falls back to the method returned by the Authorization Server, such as `client_secret_basic` or `client_secret_post`. If `tokenEndpointAuthSigningAlg` isn't configured, the `RS256` signing algorithm is used for `private_key_jwt`. Consider these points for identity providers: * Some providers accept more than one authentication method. * If a provider strictly enforces how the client must authenticate, align the authentication method with the provider. * If a provider doesn't support the authentication method, the provider sends an HTTP 400 Bad Request response with an `invalid_client` error message, according to RFC 6749 [The OAuth 2.0 Authorization Framework, section 5.2](https://tools.ietf.org/html/rfc6749#section-5.2). * If the authentication method is invalid, the provider sends an `IllegalArgumentException`. Default: `client_secret_basic` ### tokenEndpointAuthSigningAlg (deprecated) `"tokenEndpointAuthSigningAlg"`: *string, optional* | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This property is deprecated. Use [authenticatedRegistrationHandler](#ClientRegistration-authenticatedRegistrationHandler) instead. Learn more in the [Deprecated](https://docs.pingidentity.com/pinggateway/release-notes/deprecated.html) section of the *Release Notes*. | The JSON Web Algorithm (JWA) used to sign the JWT that is used to authenticate the client at the token endpoint. The property is used when `private_key_jwt` is used for authentication. Use one of the following algorithms: * `RS256`: RSA using SHA-256 * `ES256`: ECDSA with SHA-256 and NIST standard P-256 elliptic curve * `ES384`: ECDSA with SHA-384 and NIST standard P-384 elliptic curve * `ES512`: ECDSA with SHA-512 and NIST standard P-521 elliptic curve Default: `RS256` ## Example Learn more in [AM as OIDC provider](../gateway-guide/oidc-am.html). ## More information [org.forgerock.openig.filter.oauth2.client.ClientRegistration](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/ClientRegistration.html) [Issuer](Issuer.html) [The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) [The OAuth 2.0 Authorization Framework: Bearer Token Usage](https://www.rfc-editor.org/rfc/rfc6750) [OpenID Connect](https://openid.net/developers/how-connect-works//)