Skip to main content

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:

Authentication flow

  1. 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

    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 

    Yes

    tid 

    Tenant ID — used to identify the tenant in the URL

    Yes

    aid 

    Authorization server ID — identifies the specific authorization server instance

    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

    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"
}

  2. Sign the payload with the client’s private key to generate the JWT.

  3. 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'

  4. 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.

In this section: