On this page
Build a JWT for Client Authentication
This guide explains how to build a self-signed JSON Web Token (JWT) that's used throughout Okta. For example, when you make requests to Okta API endpoints that require client authentication (opens new window), you can optionally use a JWT for more security.
Note: JWTs allow claims, such as user data, to be represented in a secure manner, helping to ensure trust and security in your app. JWTs are an open standard, and there are various libraries available that allow you to create, verify, and inspect them.
Learning outcomes
- Build a signed JWT for request authentication to OpenID Connect endpoints.
- Understand which claims are required in your JWT payload.
- Sign the JWT with a shared secret or a private key.
JWT Types
There are two types of self-signed JWT assertions that you can build for use when you make requests to endpoints that require client authentication:
- JWT with a shared key (
client_secret_jwt
) - JWT with a private key (
private_key_jwt
)
The difference between building these two types of assertions is the algorithm and key used to sign the JWT.
Which JWT type you use depends on the client authentication method configured in your OAuth 2.0 client application. See Client Authentication Methods (opens new window) for more information on the supported methods and when to use them.
Note: To create a client app and specify either the
client_secret_jwt
orprivate_key_jwt
authentication method, see the parameter details (opens new window) of the Apps API reference section. To change the client authentication method of an existing app, see the Update the Client Authentication Method (opens new window) API reference section.
Tip: If you don't know which method is configured for your client app, you can quickly check the settings by doing a GET to
https://{yourOktaDomain}/api/v1/apps/{appId}
.
Gather claims information
When you create a JWT assertion claim for client authentication (client_secret_jwt
or private_key_jwt
), gather claims information for the payload section of the JWT. Claims are statements about the entity, which is typically a user and any additional data.
Claim | Description | Type |
---|---|---|
aud | Required. The full URL of the resource that you're trying to access using the JWT to authenticate. For example: https://{yourOktaDomain}/oauth2/default/v1/token | String |
exp | Required. The token expiration time in seconds since January 1, 1970 UTC (UNIX timestamp), for example, 1555594819 . This claim fails the request if the expiration time is more than one hour in the future or if the token is already expired. | Integer |
iss | Required. The issuer of the token. This value must be the same as the client_id of the application that you’re accessing. | String |
sub | Required. The subject of the token. This value must be the same as the client_id of the application that you’re accessing. | String |
jti | Optional. The unique token identifier. If you specify this parameter, the token can only be used once and, as a result, subsequent token requests don't succeed. | String |
iat | Optional. When the token was issued in seconds since January 1, 1970 UTC (UNIX timestamp), for example, 1555591219 . If specified, it must be a time before the request is received. | Integer |
Build a JWT with a shared key
If you configured your application to use the client_secret_jwt
client authentication method, then you want to build a JWT that you sign with the client_secret
using an HMAC SHA algorithm (HS256, HS384, or HS512).
Build a JWT with a private key
If you configured your client to use the private_key_jwt
client authentication method, then you want to build a JWT that you sign with your private key using an RSA or ECDSA algorithm (RS256, RS384, RS512, ES256, ES384, ES512).