On this page
Build a JWT for Client Authentication
This guide explains how to build a self-signed JSON Web Token (JWT) that is used throughout Okta. For example, when you make requests to Okta API endpoints that require client authentication, you can optionally use a JWT for additional 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.
- 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.
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 (
- JWT With a Private Key (
The difference between building these two types of assertions is the algorithm and key used to sign the JWT.
Which JWT type that you use depends on the client authentication method configured in your OAuth 2.0 client application. See Client Authentication Methods for more information on the supported methods and when to use them.
Note: To create a client application and specify either the
private_key_jwtauthentication method, see the Add OAuth 2.0 Client Application API reference section. To change the client authentication method of an existing app, see the Update the Client Authentication Method API reference section.
Tip: Don't know which method is configured for your client app? You can quickly check the settings by doing a GET to
Gather claims information
When you create a JWT assertion claim for client authentication (
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.
|aud||Required. The full URL of the resource that you're trying to access using the JWT to authenticate. For example: ||String|
|exp||Required. The token expiration time in seconds since January 1, 1970 UTC (UNIX timestamp), for example, ||Integer|
|iss||Required. The issuer of the token. This value must be the same as the ||String|
|sub||Required. The subject of the token. This value must be the same as the ||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 won't succeed.||String|
|iat||Optional. When the token was issued in seconds since January 1, 1970 UTC (UNIX timestamp), for example, ||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).