Client Certificate Claims Value Provider
The Client Certificate claims value provider extracts claims from client certificates presented during authentication. This provider accesses certificate attributes like subject distinguished name, organization identifier, PSD2 roles, and subject alternative names, enabling certificate-based authentication and authorization scenarios.
The Client Certificate claims provider retrieves claims from X.509 certificates that clients present during mutual TLS (mTLS) authentication. These attributes provide strong identity verification and enable compliance with regulations like PSD2 that require certificate-based authentication.
Use Cases#
The Client Certificate claims value provider enables certificate-based authentication and authorization scenarios.
Common use cases include:
- PSD2 Compliance: Extract PSD2 roles from qualified certificates for open banking APIs, enabling role-based authorization for Account Information Service Providers (AISPs) and Payment Initiation Service Providers (PISPs)
- Organization Verification: Include organization identifiers from certificates in tokens to verify the identity of corporate clients and business partners
- Certificate Fingerprinting: Add certificate fingerprints (SHA-1 or SHA-256) to tokens for certificate binding and token theft prevention
- Subject Identification: Use distinguished names and subject alternative names to identify certificate holders and their associated identities
- Mutual TLS Authorization: Enable APIs to make authorization decisions based on certificate attributes rather than user credentials
Getting Started#
To create a Client Certificate claims value provider, sign in to the Admin UI and navigate to Profiles → Token Service → Scopes → Claims Providers.
Select + New Claims Value Provider, give the provider a unique identifier and choose the Client Certificate type.
The provider automatically extracts attributes from the client certificate when tokens are issued. The client must present a valid certificate during the TLS handshake for this provider to return claims.
Available Attributes#
The Client Certificate claims value provider can expose the following attributes:
psd2Roles— List of PSD2 roles from qualified statements in the certificatesubjectDn— Subject distinguished name as a stringsubjectDnAttributeValueAssertions— Subject DN attribute-value pairs as an objectsubjectOrganizationIdentifier— Organization identifier from the certificate subjectx5t— Base64url-encoded SHA-1 certificate fingerprintx5t_S256— Base64url-encoded SHA-256 certificate fingerprintsubjectAlternativeNames— All subject alternative name attributes as an objectsubjectAlternativeNamesUris— List of URI entries from subject alternative namessubjectAlternativeNamesDnsNames— List of DNS name entries from subject alternative namessubjectAlternativeNamesEmails— List of email entries from subject alternative namessubjectAlternativeNamesIpAddresses— List of IP address entries from subject alternative names
The Client Certificate claims value provider only returns attributes when a client presents a certificate during mutual TLS authentication. Configure the token service to require client certificates for this provider to function.
For more information on configuring mutual TLS, see Cryptography .