--- title: AuthorizationCodeOAuth2ClientFilter description: Uses OAuth 2.0 delegated authorization to authenticate end users. The filter can act as an OpenID Connect (OIDC) relying party (RP) or as an OAuth 2.0 client. component: pinggateway version: 2026 page_id: pinggateway:reference:AuthorizationCodeOAuth2ClientFilter canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/AuthorizationCodeOAuth2ClientFilter.html revdate: 2026-01-15 section_ids: AuthorizationCodeOAuth2ClientFilter-serviceuri: Service URIs AuthorizationCodeOAuth2ClientFilter-usage: Usage AuthorizationCodeOAuth2ClientFilter-properties: Properties AuthorizationCodeOAuth2ClientFilter-clientEndpoint: clientEndpoint AuthorizationCodeOAuth2ClientFilter-failureHandler: failureHandler AuthorizationCodeOAuth2ClientFilter-loginHandler: loginHandler AuthorizationCodeOAuth2ClientFilter-registrations: registrations AuthorizationCodeOAuth2ClientFilter-metadata: metadata AuthorizationCodeOAuth2ClientFilter-cacheExpiration: cacheExpiration AuthorizationCodeOAuth2ClientFilter-executor: executor AuthorizationCodeOAuth2ClientFilter-defaultLoginGoto: defaultLoginGoto AuthorizationCodeOAuth2ClientFilter-defaultLogoutGoto: defaultLogoutGoto AuthorizationCodeOAuth2ClientFilter-requireHttps: requireHttps AuthorizationCodeOAuth2ClientFilter-requireLogin: requireLogin AuthorizationCodeOAuth2ClientFilter-revokeOauth2TokenOnLogout: revokeOauth2TokenOnLogout AuthorizationCodeOAuth2ClientFilter-openIdEndSessionOnLogout: openIdEndSessionOnLogout AuthorizationCodeOAuth2ClientFilter-prompt: prompt AuthorizationCodeOAuth2ClientFilter-issuerRepository: issuerRepository (deprecated) AuthorizationCodeOAuth2ClientFilter-useDeprecatedIssuerRepository: useDeprecatedIssuerRepository (deprecated) AuthorizationCodeOAuth2ClientFilter-discoveryHandler: discoveryHandler AuthorizationCodeOAuth2ClientFilter-discoverySecretId: discoverySecretId AuthorizationCodeOAuth2ClientFilter-tokenEndpointAuthMethod: tokenEndpointAuthMethod AuthorizationCodeOAuth2ClientFilter-tokenEndpointAuthSigningAlg: tokenEndpointAuthSigningAlg AuthorizationCodeOAuth2ClientFilter-oAuth2SessionKey: oAuth2SessionKey AuthorizationCodeOAuth2ClientFilter-secretsProvider: secretsProvider AuthorizationCodeOAuth2ClientFilter-example: Examples AuthorizationCodeOAuth2ClientFilter-moreinfo: More information --- # AuthorizationCodeOAuth2ClientFilter Uses OAuth 2.0 delegated authorization to authenticate end users. The filter can act as an OpenID Connect (OIDC) relying party (RP) or as an OAuth 2.0 client. AuthorizationCodeOAuth2ClientFilter performs the following tasks: * Allows the user to select an Authorization Server from one or more static client registrations or by discovery and dynamic registration. In static client registration, Authorization Servers are provided by [Issuer](Issuer.html), and registrations are provided by [ClientRegistration](ClientRegistration.html). * Redirects the user through the authentication and authorization steps of an OAuth 2.0 authorization code grant, which results in the Authorization Server returning an access token to the filter. * When an authorization grant succeeds, injects the access token data into the [OAuth2InfoContext](OAuth2InfoContext.html) so that subsequent filters and handlers can access the access token. Subsequent requests can use the access token without authenticating again. * When an authorization grant fails, the filter injects information about the failure into the [OAuth2FailureContext](OAuth2FailureContext.html), which is provided to the `failureHandler` object. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When this filter acts as an OIDC RP, avoid sharing the ID token with other applications or relying on the ID token claims after authentication completes and the end user's redirected to the final landing page.When this filter requests the `openid` scope, the OpenID provider returns both an access token and an ID token. If the ID token claims must remain fresh as long as the access token remains valid, align the access token and ID token lifetimes. | ## Service URIs Service URIs are constructed from the `clientEndpoint`, as follows: * `clientEndpoint/login/?discovery=user-input&goto=url` Discover and register dynamically with the end user's OpenID Provider or with the client registration endpoint as described in RFC 7591, using the value of user-input. After successful registration, redirect the end user to the provider for authentication and authorization consent. Then redirect the user agent back to the callback client endpoint, and then the goto URI. The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error. To redirect a request to a site that doesn't meet the goto URL criteria, change the original URI by using a ForwardedRequestFilter. * `clientEndpoint/login?registration=clientId&issuer=issuerName&goto=url` Redirect the end user for authorization with a registration defined by the [ClientRegistration](ClientRegistration.html) properties `clientId` and `issuerName`. The provider corresponding to the registration then authenticates the end user and obtains authorization consent before redirecting the user agent back to the callback client endpoint. If successful, the filter saves the authorization state in the session and redirects the user agent to the goto URL. The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error. To redirect a request to a site that doesn't meet the goto URL criteria, change the original URI by using a ForwardedRequestFilter. * `clientEndpoint/logout?goto=url` Remove the authorization state for the end user, and redirect the request to the goto URL. The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error. To redirect a request to a site that doesn't meet the goto URL criteria, change the original URI by using a ForwardedRequestFilter. If no goto URL is specified in the request, use `defaultLogoutGoto`. * `clientEndpoint/callback` Handle the callback from the OAuth 2.0 Authorization Server occuring as part of the authorization process. If the callback is handled successfully, the filter saves the authorization state in the [OAuth2InfoContext](OAuth2InfoContext.html) and redirects to the URL provided to the login endpoint during login. * Other request URIs Restore the authorization state in the [OAuth2InfoContext](OAuth2InfoContext.html) and call the next filter or handler in the chain. ## Usage ```none { "name": string, "type": "AuthorizationCodeOAuth2ClientFilter", "config": { "clientEndpoint": runtime expression, "failureHandler": Handler reference, "loginHandler": Handler reference, "registrations": [ ClientRegistration reference, …​ ], "metadata": object, "cacheExpiration": configuration expression, "executor": ScheduledExecutorService reference, "defaultLoginGoto": runtime expression, "defaultLogoutGoto": runtime expression, "requireHttps": configuration expression, "requireLogin": configuration expression, "revokeOauth2TokenOnLogout": configuration expression, "openIdEndSessionOnLogout": configuration expression, "prompt": configuration expression, "issuerRepository": IssuerRepository reference, // deprecated "useDeprecatedIssuerRepository": configuration expression, // deprecated "discoveryHandler": Handler reference, "discoverySecretId": configuration expression, "tokenEndpointAuthMethod": configuration expression, "tokenEndpointAuthSigningAlg": configuration expression, "oAuth2SessionKey": configuration expression, "secretsProvider": SecretsProvider reference } } ``` ## Properties ### clientEndpoint `"clientEndpoint"`: *runtime expression<[url](preface.html#definition-url)>, required* The URI to the client endpoint. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------- | | | This endpoint must remain unique to this filter and route. Don't reuse it in other routes or filters or in protected applications. | So that routes can accept redirects from the Authorization Server to the callback endpoint, the `clientEndpoint` must be the same as the route condition or a sub path of the route condition: * The same as the route condition: ```none "condition": "${find(request.uri.path, '^/discovery')}" ``` ```none "clientEndpoint": "/discovery" ``` * As a sub path of the route condition: ```none "condition": "${find(request.uri.path, '^/home/id_token')}" ``` ```none "clientEndpoint": "/home/id_token/sub-path" ``` Service URIs are constructed from the `clientEndpoint`. For example, when `clientEndpoint` is `openid`, the service URIs are `/openid/login`, `/openid/logout`, and `/openid/callback`. These endpoints are implicitly reserved and attempts to access them directly can cause undefined errors. The result of the expression must be a string that represents a valid URI, but isn't a real `java.net.URI` object. For example, it would be incorrect to use `${request.uri}`, which isn't a String but a MutableUri. Learn more in [PingGateway expressions](Expressions.html). ### failureHandler `"failureHandler"`: *Handler [reference](preface.html#definition-reference), optional* An inline handler configuration object or the name of a handler object defined in the heap. When the OAuth 2.0 Resource Server denies access to a resource, the failure handler can only be invoked if the error response contains a WWW-Authenticate header, which means there was a problem with the OAuth 2.0 exchange. All other responses are forwarded to the user agent without invoking the failure handler. If the value of the WWW-Authenticate header is `invalid_token`, the AuthorizationCodeOAuth2ClientFilter tries to refresh the access token: * If the token is refreshed, the AuthorizationCodeOAuth2ClientFilter tries again to access the protected resource. * If the token isn't refreshed, or if the second attempt to access the protected resource fails, the AuthorizationCodeOAuth2ClientFilter invokes the failure handler. You can configure the handler to access information in [OAuth2FailureContext](OAuth2FailureContext.html). Default: Fail with an HTTP 500 Internal Server error and log an exception with the failure context. ### loginHandler `"loginHandler"`: *Handler [reference](preface.html#definition-reference), required if there are zero or multiple client registrations, optional if there is one client registration* The handler to invoke when the user must select a registered identity provider for login. When `registrations` contains only one client registration, this handler is optional but is displayed if specified. Provide the name of a [Handler](Handlers.html) object defined in the heap or an inline handler configuration object. When you use `loginHandler` in AuthorizationCodeOAuth2ClientFilter, retrieve the original target URI for the request from `${contexts.idpSelectionLogin.originalUri}`. Learn more in [IdpSelectionLoginContext](IdpSelectionLoginContext.html). ### registrations `"registrations"`: *array of ClientRegistration [references](preface.html#definition-reference) optional* List of client registrations to authenticate PingGateway to the Authorization Server. The value represents a static [ClientRegistration](ClientRegistration.html) with an Authorization Server. ### metadata `"metadata"`: *<[object](preface.html#definition-object)>, required for dynamic client registration and ignored otherwise* The values of the object are evaluated as configuration expression<[strings](preface.html#definition-string)>. This object holds the client metadata described in [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) and optionally a list of scopes. This object can also hold the client metadata described in RFC 7591, [OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591). The following partial list of metadata fields isn't exhaustive. It includes metadata that is useful with AM as OpenID Provider: * `"redirect_uris"`: *array of configuration expression<[url](preface.html#definition-url)>, required* The array of redirection URIs to use when dynamically registering this client. One of the registered values **must** match the `clientEndpoint`. * `"client_name"`: *configuration expression<[string](preface.html#definition-string)>, optional* Name of the client to present to the end user. * `"scope"`: *\_configuration expression<[string](preface.html#definition-string)>, optional* Space-separated string of scopes to request of the OpenID Provider, for example: ```none "scope": "openid profile" ``` This property is available for dynamic client registration with AM and with Authorization Servers that support RFC 7591, [OAuth 2.0 Dynamic Client Registration Protocol](https://www.rfc-editor.org/rfc/rfc7591). * `"pkce_method"`: *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` ### cacheExpiration `"cacheExpiration"`: *configuration expression<[duration](preface.html#definition-duration)>, optional* Duration for which to cache user-info resources. PingGateway lazily fetches user info from the OpenID provider. In other words,PingGateway only fetches the information when a downstream Filter or Handler uses the user info. Caching allows PingGateway to avoid repeated calls to OpenID providers when reusing the information over a short period. Set this to disabled or zero to disable caching. When caching is disabled, user info is still lazily fetched. Default: 10 minutes ### executor `"executor"`: *ScheduledExecutorService [reference](preface.html#definition-reference), optional* A [ScheduledExecutorService](ScheduledExecutorService.html) to schedule the execution of tasks, such as the eviction of entries in the OpenID Connect user information cache. Default: `ScheduledExecutorService` ### defaultLoginGoto `"defaultLoginGoto"`: *runtime expression<[url](preface.html#definition-url)>,optional* After successful authentication and authorization, if the user accesses the `clientEndpoint/login` endpoint without providing a landing page URL in the `goto` parameter, the request is redirected to this URI. The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error. To redirect a request to a site that doesn't meet the goto URL criteria, change the original URI with a [ForwardedRequestFilter](ForwardedRequestFilter.html). The result of the expression must be a string that represents a valid URI, but isn't a real `java.net.URI` object. For example, it would be incorrect to use `${request.uri}`, which is not a String but a MutableUri. Default: return an empty page. ### defaultLogoutGoto `"defaultLogoutGoto"`: *runtime expression<[url](preface.html#definition-url)>,optional* If the user accesses the `clientEndpoint/logout` endpoint without providing a goto URL, the request is redirected to this URI. The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error. To redirect a request to a site that doesn't meet the goto URL criteria, change the original URI with a [ForwardedRequestFilter](ForwardedRequestFilter.html). The result of the expression must be a string that represents a valid URI, but is not a real `java.net.URI` object. For example, it would be incorrect to use `${request.uri}`, which is not a String but a MutableUri. Default: return an empty page. ### requireHttps `"requireHttps"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether to require that original target URI of the request uses the HTTPS scheme. If the received request doesn't use HTTPS, it is rejected. Default: `true` ### requireLogin `"requireLogin"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether to require authentication for all incoming requests. Default: `true` ### revokeOauth2TokenOnLogout `"revokeOauth2TokenOnLogout"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* When `true`, call the `revocationEndpoint` defined in [Issuer](Issuer.html) to revoke the access token or refresh token issued by the Authorization Server during login. If this property is `false` or if `revocationEndpoint` in Issuer isn't defined, PingGateway doesn't revoke the tokens. Processing errors generate warnings in the logs but don't break the logout flow. Default: `false` ### openIdEndSessionOnLogout `"openIdEndSessionOnLogout"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* When `true`, redirect the user to the `endSessionEndpoint` defined in [Issuer](Issuer.html) to log the user out of the Authorization Server. Use this property to initiate logout from an OpenID Connect resource provider. If this property is `false` or if `endSessionEndpoint` in Issuer isn't defined, PingGateway doesn't redirect the user to log the user out of the Authorization Server. If the user accesses the `endSessionEndpoint` endpoint without providing a goto URL, PingGateway redirects the request to the `defaultLogoutGoto`. Learn more in [OpenID Connect Session Management](https://openid.net/specs/openid-connect-session-1_0-10.html). Default: `false` ### prompt `"prompt"`: *configuration expression<[string](preface.html#definition-string)>, optional* A space-separated, case-sensitive list of strings that indicate whether to prompt the end user for authentication and consent. Use in [OIDC flows](https://openid.net/specs/openid-connect-core-1_0.html) only. Read the Authorization Server documentation for information about supported `prompt` values. For example, learn more in [prompt](https://docs.pingidentity.com/pingoneaic/am-oauth2/oauth2-parameters.html#prompt) in the PingOne Advanced Identity Cloud documentation or [prompt](https://docs.pingidentity.com/pingam/8.1/am-oauth2/oauth2-parameters.html#prompt) in the AM documentation. PingGateway provides the following values: * `none`: Don't display authentication or consent pages. Don't use this value in the same list as `login`, `consent`, or `select_account`. * `login`: Prompt the end user to reauthenticate even if they have a valid session on the Authorization Server. * `consent`: Prompt the end user to consent before returning information to the client, even if they have already consented in the session. * `select_account`: Prompt the end user to select a user account. Prompt the end user to reauthenticate ```none "prompt": "login" ``` Prompt the end user to reauthenticate and consent ```none "prompt": "login consent" ``` ### issuerRepository (deprecated) `"issuerRepository"`: *Issuer repository [reference](preface.html#definition-reference), optional* A repository of OAuth 2.0 issuers, built from discovered issuers and the PingGateway configuration. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The [IssuerRepository (deprecated)](IssuerRepository.html) is deprecated.For issuers known in advance, add their settings to the [ClientRegistration](ClientRegistration.html).For discovery, if the `IssuerRepository` had an `"issuerHandler"`, configure an `AuthorizationCodeOAuth2ClientFilter` `"discoveryHandler"` instead. | Provide the name of an IssuerRepository object defined in the heap. Default: Look up an issuer repository named `IssuerRepository` in the heap. If none is explicitly defined, a default one named `IssuerRepository` is created in the current route. ### useDeprecatedIssuerRepository (deprecated) `"useDeprecatedIssuerRepository"`: *configuration expression<[boolean](preface.html#definition-boolean)>, optional* Whether to use the deprecated default `"IssuerRepository"` from the heap. | | | | - | ---------------------------- | | | This property is deprecated. | * `true`: When the `"issuerRepository"` isn't set, use the deprecated default `"IssuerRepository"` from the heap. * `false`: When the `"issuerRepository"` isn't set, don't use the deprecated default `"IssuerRepository"` and don't share registered or discovered issues with any [AuthorizationCodeOAuth2ClientFilter](AuthorizationCodeOAuth2ClientFilter.html)s. Default: `false` ### discoveryHandler `"discoveryHandler"`: *Handler [reference](preface.html#definition-reference), optional* Use this property for discovery and dynamic registration of OpenID Connect clients. Provide either the name of a Handler object defined in the heap or an inline [Handler](Handlers.html) 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: The default ClientHandler. ### discoverySecretId `"discoverySecretId"`: *configuration expression<[secret-id](preface.html#definition-secretid)>, required for discovery and dynamic registration* Use this property for discovery and dynamic registration of OAuth 2.0 clients. This secret ID must point to a [CryptoKey](../security-guide/keys.html#secret-types). This specifies the secret ID of the secret used to sign a JWT before the JWT is sent to the Authorization Server. If `discoverySecretId` is used, then the `tokenEndpointAuthMethod` is always `private_key_jwt`. ### tokenEndpointAuthMethod `"tokenEndpointAuthMethod"`: *configuration expression<[enumeration](preface.html#definition-enumeration)>, optional* Use this property for discovery and dynamic registration of OAuth 2.0 clients. The authentication method with which a client authenticates to the authorization server or OpenID provider at the token endpoint. Learn about client authentication methods in the OpenID document 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 HTTP basic access authentication: ```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 on the method returned by the Authorization Server; for example, `client_secret_basic` or `client_secret_post`. If `tokenEndpointAuthSigningAlg` is not 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: Error Response](https://www.rfc-editor.org/rfc/rfc6749#section-5.2). * If the authentication method is invalid, the provider sends an `IllegalArgumentException`. Default: If `discoverySecretId` is used, then the `tokenEndpointAuthMethod` is always `private_key_jwt`. Otherwise, it is `client_secret_basic`. ### tokenEndpointAuthSigningAlg `"tokenEndpointAuthSigningAlg"`: *configuration expression<[string](preface.html#definition-string)>, optional* 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. If the Authorization Server sends a notification to use a different algorithm to sign the JWT, that algorithm is used. Default: If `discoverySecretId` is used, then the `tokenEndpointAuthSigningAlg` is `RS256`. Otherwise, it is not used. ### oAuth2SessionKey `"oAuth2SessionKey"`: *configuration expression<[string](preface.html#definition-string)>, optional* A key to identify an OAuth 2.0 session. The key can be any character string. To share the same OAuth 2.0 session when a user accesses different applications protected by PingGateway, use the same key in each filter. Default: The complete client endpoint URI. AuthorizationCodeOAuth2ClientFilters don't share OAuth 2.0 sessions. ### secretsProvider `"secretsProvider"`: *SecretsProvider [reference](preface.html#definition-reference), required if `discoverySecretId` is used* The [SecretsProvider](SecretsProvider.html) to query for passwords and cryptographic keys. ## Examples You can find more information in the following pages: * [AM as OIDC provider](../gateway-guide/oidc-am.html) * [Multiple OIDC providers using PingAM and PingOne Advanced Identity Cloud](../gateway-guide/oidc-nascar.html) * [Discovery and dynamic registration with PingAM](../gateway-guide/oidc-dynamic.html) ## More information [org.forgerock.openig.filter.oauth2.client.AuthorizationCodeOAuth2ClientFilter](../_attachments/apidocs/org/forgerock/openig/filter/oauth2/client/AuthorizationCodeOAuth2ClientFilter.html) [Issuer](Issuer.html) [ClientRegistration](ClientRegistration.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/) site, in particular the list of standard OpenID Connect 1.0 [scope values](https://openid.net/specs/openid-connect-basic-1_0.html#Scopes).