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| Parameter | Type | Required | Description |
|---|---|---|---|
client_id | String | O | The client ID of the application. |
response_type | String | O | grant |
redirect_uri | String | O | The redirect URI of the application. If you registered multiple redirect_uris, you must select one. |
scope | String | X | The OAuth scopes granted to the access token, separated by spaces. Currently, the embedded_signing scope is not support for Authorization Code Flow. |
state | String | X | A 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:
- Before redirecting the user to Step 1, generate a random, unguessable
stateand store it on your server together with the user's email. - When the user is redirected back, verify that
statematches a value you issued and has not been used before, then retrieve the stored email. - Use the email as the
subclaim in Step 3. If Step 4 returnsinvalid_grant, the user may have granted the authorization with a different DottedSign account, or the requestedscopeexceeds 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.comfor production andhttps://sandbox.dottedsign.comfor 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| Parameter | Type | Required | Description |
|---|---|---|---|
grant_type | String | O | urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | String | O | The 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| Parameter | Type | Required | Description |
|---|---|---|---|
client_id | String | O | Client ID for the application. |
client_secret | String | O | Client secret for the application. |
grant_type | String | O | refresh_token |
refresh_token | String | O | The refresh token obtained through previous steps. |
Updated 3 days ago
