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:

Prerequisites

  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)

    Note

    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.

Process

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

    Example

    {
    "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.

    Result

    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.
    eyJpc3N1ZXIiOiJZekV6TUdkb01ISm5PSEJpT0cxaWJEaHlOVEE9Iiwic3ViamVjdCI6Ill6RXpN
    R2RvTUhKbk9IQmlPRzFpYkRoeU5UQT0iLCJzY29wZSI6ImludHJvc2NwZWN0X3Rva2VucywgcmV2
    b2tlX3Rva2VucyIsImF1ZCI6Imh0dHBzOi8vbG9jYWxob3N0Ojg0NDMve3RpZH0ve2FpZH0vb2F1
    dGgyL2F1dGhvcml6ZSIsImp3dElEIjoiMTUxNjIzOTAyMiIsImV4cGlyYXRpb25UaW1lIjoiMjAy
    MS0wNS0xN1QwNzowOTo0OC4wMDArMDU0NSJ9.
    PkkBvc1oPLdSXCqKdf5r2-is51CFvLVbdM9GYmzRvGqnxFK7MyKgSEqA0wZzC0rc8q7TAx2AwpFQ
    E-Ea1MKQEW1qViyl2MwUcbg8QHN1dSZez_eMpmQiQUiIuZKJYbrjlbKypXPCGcTL8YVkDrA2F6ny
    El1BpVvT8s-yeQX7VpfiKcKHApF0d_jnDizGCpwxnsSlobgjXRftMKoeyChKnF3y-KI33LrcP3n-
    Mvr9Y12vN39PV4JTzcBSqU4g8rjDtPt2Z1swXjEO4X6DQmso5L09a_Wb7vf9umaOJfP3luye7Uyj
    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.

Result

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.

Info

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.