PingGateway 2024.9

ConfirmationKeyVerifierAccessTokenResolver

In OAuth2ResourceServerFilter, use the ConfirmationKeyVerifierAccessTokenResolver to verify that certificate-bound OAuth 2.0 bearer tokens presented by clients use the same mTLS-authenticated HTTP connection.

When a client obtains an access token from AM by using mTLS, AM can optionally use a confirmation key to bind the access token to a certificate. When the client connects to PingGateway using that certificate, the ConfirmationKeyVerifierAccessTokenResolver verifies that the confirmation key corresponds to the certificate.

This proof-of-possession interaction ensures that only the client in possession of the key corresponding to the certificate can use the access token to access protected resources.

To use the ConfirmationKeyVerifierAccessTokenResolver, the following configuration is required in AM:

  • OAuth 2.0 clients must be registered using an X.509 certificate, that is self-signed or signed in public key infrastructure (PKI)

  • The AM client authentication method must be self_signed_client_auth or tls_client_auth.

  • AM must be configured to bind a confirmation key to each client certificate.

The ConfirmationKeyVerifierAccessTokenResolver delegates the token resolution to a specified AccessTokenResolver, which retrieves the token information. The ConfirmationKeyVerifierAccessTokenResolver verifies the confirmation keys bound to the access token, and then acts as follows:

  • If there is no confirmation key, pass the request down the chain.

  • If the confirmation key matches the client certificate, pass the request down the chain.

  • If the confirmation key doesn’t match the client certificate, throw an error.

  • If the confirmation key method is not supported by PingGateway, throw an error.

For an example that uses the ConfirmationKeyVerifierAccessTokenResolver, refer to Mutual TLS.

For information about issuing certificate-bound OAuth 2.0 access tokens, refer to Certificate-bound proof-of-possession in AM’s OAuth 2.0 guide. For information about authenticating an OAuth 2.0 client using mTLS certificates, refer to Mutual TLS in AM’s OAuth 2.0 guide .

Usage

Use this resolver with the accessTokenResolver property of OAuth2ResourceServerFilter.

"accessTokenResolver": {
  "type": "ConfirmationKeyVerifierAccessTokenResolver",
  "config": {
    "delegate": AccessTokenResolver reference
  }
}

Properties

"delegate": AccessTokenResolver reference, required

The access token resolver to use for resolving access tokens. Use any access token resolver described in Access token resolvers.

Examples

For an example that uses the ConfirmationKeyVerifierAccessTokenResolver with the following route, refer to Mutual TLS.

Copyright © 2010-2024 ForgeRock, all rights reserved.