Authorization Basics

Private Key JWT Client Authentication

Description of the Cloudentity private_key_jwt based authentication flow

JWTs in a Nutshell

JSON Web Tokens are an open standard that defines a compact and secure way of transmitting data between parties using a JSON object. Such information can be digitally signed with a secret (using the Hash Message Authentication Code (HMAC) algorithm) or a public and private key pair (using RSA or ECDSA), therefore it can be trusted and verified.

Learn More

For a detailed description of JWT, see JSON Web Token for authorizing access.

private_key_jwt Authentication Flow

One of the methods of client authentication supported by Cloudentity is using the private_key_jwt. This method uses a client-generated JWT signed with an asymmetric key to confirm the client’s identity. Cloudentity can extract client assertion from the request and verify it with the public key.

Used Standards

Cloudentity processes requests for client authentication using the following standards:


  1. The client is registered with the private_key_jwt method as the token authentication method.

  2. A public and a private key pair set is prepared on the client-side.

  3. The client’s public key is converted from the PEM format to a jwks (JSON Web Key Set)


    You can put your jwks on a server of your choice to enable using jwks_uri.

  4. jwks or jwks_uri public key is added to Cloudentity in the client’s Oauth configuration.


  1. The client prepares a JSON with the request data.


    "iss" : "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
    "sub" : "YzEzMGdoMHJnOHBiOG1ibDhyNTA=",
    "aud" : "https://localhost:8443/{tid}/{aid}/oauth2/authorize",
    "jti" : "1516235555",
    "exp" : "2021-05-17T07:09:48.000+0545" }
  2. Prepared data is signed using the private key.


    A JSON Web Token is created.

  3. The client makes a request for an access token to the token endpoint including the following parameters:

    parameter value type
    client_assertion_type urn:ietf:params:oauth:client-assertion-type:jwt-bearer Required
    client_assertion Must contain a single JSON Web Token. Required
    grant_type Type of the grant used, for example, client_credentials Required

    Request example

    Extra line breaks are added for display purposes.

    curl --request
    -F "grant_type=client_credentials"
    -F "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    -F "client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
    4fMTCNchZu0pFxq98-Dq13rdiXHOGsV0f0SkJw"  POST \
    --url <https://localhost:8443/{tid}/{aid}/oauth2/token> \
    --header 'accept: application/x-www-form-urlencoded'
  4. Cloudentity generates an access token and provides it to the client after a successful request validation.

    Cloudentity can extract the client’s assertion and verify it using the public key.


The client is authenticated using the private_key_jwt flow.

When To Use

In general, client authentication using the private_key_jwt method should be used by companies that need to use secure client authentication flows. This may be the case, for example, for businesses that must comply with the Financial-Grade API (FAPI) standards.


FAPI is an industry-led specification of JSON data schemas, security and privacy protocols that were designed mostly for commercial and investment banking accounts, or insurance, and credit card accounts.

Updated: Aug 8, 2022