Private key JWT client authentication
Use the private_key_jwt method to authenticate a client by signing a JSON Web Token (JWT) with an asymmetric key. The authorization server verifies the JWT using the client's public key.
Prerequisites
Before using private_key_jwt, ensure the following:
- The authorization server supports the
private_key_jwtauthentication method - The client is registered to use
private_key_jwt - A public/private key pair generated and available on the client side
- The client's public key is converted from the PEM to JWKS (JSON Web Key Set) format
- The JWKS or a
jwks_uriis added to the client's OAuth configuration on the authorization server
Authentication flow
- The client prepares a signed JWT with the following claims:
| Parameter | Description | Required |
|---|---|---|
iss | Issuer - set to the client_id | Yes |
sub | Subject - set to the client_id | Yes |
aud | Audience - set to the token endpoint or issuer URL of the authorization server | Yes |
jti | Unique JWT ID to prevent replay attacks | Yes |
iat | Issued-at time in UNIX seconds | Yes |
exp | Expiration time in UNIX seconds | Yes |
Audience (aud) parameter details
Note: The following values help identify the correct token endpoint.
{tid}represents the tenant ID{aid}represents the authorization server ID
Examples:
https://{tid}.us.connect.secureauth.com/{tid}/{aid}https://{tid}.us.connect.secureauth.com/{tid}/{aid}/oauth2/token
For certificate-bound tokens, use the MTLS version:
https://{tid}.mtls.us.connect.secureauth.com/{tid}/{aid}https://{tid}.mtls.us.connect.secureauth.com/{tid}/{aid}/oauth2/token
Example JWT payload:
{
"iss" : "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
"sub" : "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
"aud" : "https://{tid}.us.connect.secureauth.com/{tid}/{aid}",
"jti" : "a3a2fc6e-29e3-4b4d-9284-615982c213c4",
"iat" : "1516238941",
"exp" : "1516239022"
}
-
Sign the payload with the client's private key to generate the JWT.
-
Send a token request to the authorization server:
| Parameter | Value | Required |
|---|---|---|
grant_type | client_credentials | Yes |
client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer | Yes |
client_assertion | The signed JWT | Yes |
Example request:
curl --request POST \
-F "grant_type=client_credentials" \
-F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
-F "client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
--url "https://{tid}.us.connect.secureauth.com/{tid}/{aid}/oauth2/token" \
--header 'accept: application/x-www-form-urlencoded'
- The authorization server validates the request, verifies the JWT using the public key, and issues an access token.
When to use private_key_jwt
Use the private_key_jwt for high-security client authentication scenarios. It is recommended for organizations that follow Financial-grade API (FAPI) standards.