OpenID Connect mutual TLS client authentication and certificate-bound access token

Edit online

OpenID Connect for Open Banking applications can be configured to use a mutual TLS (MTLS) client certificate for client authentication. Register the details of the client's certificate so that client authentication can be performed with the certificate instead of storing and using a client secret.

Access and refresh tokens can be bound to the certificate that is used to establish a mutual TLS connection with IBM® Verify at the https://{{tenant}}/oauth2/token endpoint. This connection is used as a "proof-of-possession" when the resource server needs to validate the token and enforce that the same certificate must be present to use that particular access token. This "proof-of-possession" prevents the use of stolen access tokens to access protected resources. Introspecting this token returns the "cnf" confirmation method claim, which contains the certificate thumbprint.
{
	"iss": "https://server.example.com",
	"sub": "ty.webb@example.com",
	"exp": 1493726400,
	"nbf": 1493722800,
	"cnf": {
		"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
	}
}
Note: MTLS client authentication is not a prerequisite for certificate-bound access tokens. Another client authentication method, for example private key JWT, can be used for the client authentication, while the generated access token can still be bound to a certificate.

Prerequisites

  • Configure a custom domain name for the tenant, along with a registered CA bundle. This would typically be provided when creating or updating the Verify tenant.
  • Configure the relying party client to use mutual TLS client authentication.
  • Configure the resource server or resource API gateway to verify certificate-bound access tokens.

Procedure

  1. Create API client with "Manage federations" entitlement enabled. See Creating API clients.
  2. Get a token using the API client credentials. See Managing OIDC tokens.
  3. Use the token to access the endpoint to configure federation. Update the OpenID Connect federation with a new value for mtlsEndpointBaseURI. The value of this configuration parameter is the URL that contains the HTTPS schema and custom domain name. For example, https://customdomain.jke.com. See the API documentation for OpenID Connect federation endpoint.
  4. To create or modify the OpenID Connect for Open Banking application, ensure that the following settings are configured.
    • Set the client authentication method to Mutual TLS.
    • Set the TLS client authentication attribute to one of the supported attributes. For example, the subject alternative name email address SAN email address. This attribute is the certificate attribute that is matched when TLS client authentication is performed.
    • Set the TLS client authentication attribute value to the value that is going to be matched. For example, if SAN email address attribute was selected, this attribute is the email address.
    • Enable certificate-bound access tokens.