The JWT Authorization Grant Flow is an authorization mechanism where the application directs users to an authentication page for login and authorization. After successful authorization, the application is granted long-term access, allowing it to act on behalf of the user. This method is particularly suitable for third-party platforms that require long-term authorization and do not have database service. Originally designed to enable applications to operate on behalf of users, the JWT Authorization Grant Flow ensures that user credentials are not directly exposed to the application. Instead, it uses a one-time authorization mechanism to maintain a secure authorization process.

Prerequisite

To initiate the JWT authorization grant flow, it is essential to ensure that a redirect URL is configured in your application. This redirect URL is used to redirect the user back to your application after the authorization process.

Flow

Step 1: Request for Authorization Code

GET /v1/oauth/authorize

Step 2: Receive Authorization Grant Notification

Once the user logs in successfully, DottedSign redirects the user to redirect_uri, which is provided as a parameter during the authorization request. It is crucial that the redirect_uri used in both steps matches to ensure a secure authorization process.

Step 3: Generate JWT Assertion

Follow RFC7519 to generate a JWT assertion, it consist of three parts separated by dots (.), which are header, payload and signature.

Header

The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, which is HS512 in this flow.

{
  "alg": "HS512",
  "typ": "JWT"
}

Payload

The second part of a JWT is the payload, which contains a set of claims. In this flow, the token will include five registered claims and one public claim.

• iss (issuer): The application ID that issues the token.
• sub (subject): The user email that the token refers to.
• aud (audience): The intended recipient of the token, i.e., the DottedSign domain (https://dottedsign.com for production and https://sandbox.dottedsign.com for sandbox).
• iat (issued at): The timestamp indicating when the token was issued.
• exp (expiration time): The timestamp when the token will expire, should set to 10 minutes after issuance.
• scope: The OAuth scopes granted to the access token, separated by spaces.

{
  "iss": "fJH_1y0AygugMgdFXQTYbuywmHYgqWzKXeOpEWeKDfc",
  "sub": "[email protected]",
  "aud": "https://dottedsign.com",
  "iat": "1735689600",
  "exp": "1735690200",
  "scope": "sign_tasks.general.read sign_tasks.general.read"
}

Signature

The signature is used to verify the integrity and authenticity of the token.

To create the signature, you concatenate the Base64Url-encoded header and payload with a period (.), then sign the result using HMAC-SHA512 with the application's secret.

HMACSHA512(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  application.secret
)

Step 4: Exchange JWT Assertion for Access Token

POST /v1/oauth/token

Refresh Token

The access token obtained has a distinct lifetime, configured in the application for security considerations. Once it expires, all subsequent API requests will receive a 401 "Unauthorized" response. Therefore, it is necessary to refresh the token regularly to maintain uninterrupted API access.

POST /v1/oauth/token