JWT Authorization Grant Flow

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
ParameterTypeRequiredDescription
client_idStringOThe client ID of the application.
response_typeStringOgrant
redirect_uriStringOThe redirect URI of the application. If you registered multiple redirect_uris, you must select one.
scopeStringXThe OAuth scopes granted to the access token, separated by spaces. Currently, the embedded_signing scope is not support for Authorization Code Flow.
stateStringXA value generated by your application. It is returned unchanged when redirecting to redirect_uri. Strongly recommended, see Step 2.

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.

Unlike the Authorization Code Flow, the redirect does not include an authorization code or any information about the user. Only the state provided in Step 1 is appended to redirect_uri:

https://example.com/callback?state=8f3a1c9e2b7d4f60

The JWT assertion in Step 3 requires the email of the user who granted the authorization. Your application must already know this email, and use state to associate the redirect with it:

  1. Before redirecting the user to Step 1, generate a random, unguessable state and store it on your server together with the user's email.
  2. When the user is redirected back, verify that state matches a value you issued and has not been used before, then retrieve the stored email.
  3. Use the email as the sub claim in Step 3. If Step 4 returns invalid_grant, the user may have granted the authorization with a different DottedSign account, or the requested scope exceeds the granted scopes.

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
ParameterTypeRequiredDescription
grant_typeStringOurn:ietf:params:oauth:grant-type:jwt-bearer
assertionStringOThe JWT assertion.

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
ParameterTypeRequiredDescription
client_idStringOClient ID for the application.
client_secretStringOClient secret for the application.
grant_typeStringOrefresh_token
refresh_tokenStringOThe refresh token obtained through previous steps.

Did this page help you?