OAuth 2.0 with JWT Bearer Auth

The OAuth 2.0 JWT Bearer authentication method allows you to obtain an Access Token using a JWT (JSON Web Token). This JWT represents the user’s identity and permissions and replaces traditional username-password authentication.

Once obtained, the Access Token is used to authenticate API requests as a Bearer Token. When it expires, you can use a new JWT to request a fresh Access Token, maintaining secure access without re-authentication.

Authentication Options

Two-Step Authentication Process

OAuth 2.0 with JWT Bearer authentication follows a two-step process:

1. Generate a JWT from the provided configuration parameters - We construct a JWT using the issuer, audience, subject, expiry, and additional claims configured by the user.
2. Exchange the JWT for an Access Token (if applicable) - If a token request URL is provided, the JWT is sent to the authorization server to obtain an Access Token. If no URL is provided, the JWT itself is used as the Bearer Token in API requests.

Step 1: How We Generate the JWT

We generate the JWT based on the configured values in the authentication setup:

1
import jwt
2
import time
3
4
# Example of how the system constructs the JWT
5
private_key = config["Jwt Auth Private Key"]
6
algorithm = config["Jwt Auth Algorithm"]
7
8
payload = {
9
    "iss": config["Jwt Auth Claims Issuer"],
10
    "sub": config["Jwt Auth Claims Subject"],
11
    "aud": config["Jwt Auth Claims Audience"],
12
    "iat": int(time.time()),
13
    "exp": int(time.time()) + int(config["Jwt Auth Claims Expiry Seconds"]),
14
    **config.get("Jwt Auth Additional Claims", {})  # Merging any extra claims
15
}
16
17
headers = config.get("Jwt Auth Headers", {})
18
19
jwt_token = jwt.encode(payload, private_key, algorithm=algorithm, headers=headers)

Step 2: Exchange JWT for an Access Token (if applicable)

If a token request URL is provided, the system will send the JWT to the authorization server and extract the Access Token from the response:

$
curl -X POST "$(config['Jwt Auth OAuth2 Access Token Request URL'])" \
>
     -H "Content-Type: application/x-www-form-urlencoded" \
>
     -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
>
     -d "assertion=$jwt_token"

A successful response might look like this:

1
{
2
    "access_token": "YOUR_ACCESS_TOKEN",
3
    "token_type": "Bearer",
4
    "expires_in": 3600
5
}

The system will extract access_token from this response and use it for subsequent API requests.

If no token request URL is provided, the system will use the JWT itself as the Bearer Token.

Step 3: Use the Access Token in API Requests

Once the Access Token is determined, it is included in API requests:

$
curl -X GET "https://api.example.com/data" \
>
     -H "Authorization: Bearer $ACCESS_TOKEN"

Where $ACCESS_TOKEN is either:

• The JWT itself (if no token request URL was provided)
• The extracted access token from the authorization server’s response

Configuration Fields

To set this up:

1. Select JWT Auth from the Auth Config dropdown.

2. Fill in the required fields:

   Field Name	Field Value
   Jwt Auth Private Key	Upload your Private Key or 256-bit secret. See JWT.io for formatting details.
   Jwt Auth Algorithm	Select from HS256, RS256, or ES256, as specified by the system you are integrating with.
   Jwt Auth Claims Expiry Seconds	Set the expiration time in seconds (e.g., 3600). The exp claim is calculated as iat + this value.
   Jwt Auth Claims Issuer	The iss claim value.
   Jwt Auth Claims Audience	The aud claim value.
   Jwt Auth Claims Subject	The sub claim value.
   Jwt Auth Headers	Any additional header claims, such as alg, typ, or kid.
   Jwt Auth Additional Claims	Any extra payload claims, such as scope or name.
   Assertion Key (optional)	Optional key used to pass the JWT assertion. If no key is specified, the standard ‘assertion’ is used.
   Jwt Auth Oauth2 Access Token Request Url	The full token request URL. If provided, the JWT is sent to this URL to obtain an Access Token.
   Custom Grant Type (Optional)	Optionally override the default grant type (urn:ietf:params:oauth:grant-type:jwt-bearer).

For testing and validation, you can use JWT.io. The iat and exp claims are automatically generated and do not need to be manually specified in the configuration.