开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

Java JWT

A Java implementation of JSON Web Token (JWT) - RFC 7519.

⚠️ Important security note: JVM has a critical vulnerability for ECDSA Algorithms - CVE-2022-21449. Please review the details of the vulnerability and update your environment.

If you're looking for an Android version of the JWT Decoder take a look at our JWTDecode.Android library.

You are viewing the documentation for the v4 beta release. For the latest stable release, please see the version 3.x documentation.

Table of Contents

• Requirements
• Installation
• Available Algorithms
• Quickstart
  • Create and Sign a Token
  • Verify a Token
• Usage
  • Pick the algorithm
  • Time Validation
  • Header Claims
  • Payload Claims
  • Claim Class
• Javadoc

Requirements

This library is supported for Java 8, 11, and 17. For issues on non-LTS versions above 8, consideration will be given on a case-by-case basis.

Installation

Gradle

implementation 'com.auth0:java-jwt:3.19.0'

Maven

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>3.19.2</version>
</dependency>

Gradle

implementation 'com.auth0:java-jwt:3.19.2'

Available Algorithms

The library implements JWT Verification and Signing using the following algorithms:

Note - Support for ECDSA with curve secp256k1 and SHA-256 (ES256K) has been dropped since it has been disabled in Java 15

Quickstart

Create and Sign a Token

You'll first need to create a JWTCreator instance by calling JWT.create(). Use the builder to define the custom Claims your token needs to have. Finally to get the String token call sign() and pass the Algorithm instance.

• Example using HS256

  try {
      Algorithm algorithm = Algorithm.HMAC256("secret");
      String token = JWT.create()
          .withIssuer("auth0")
          .sign(algorithm);
  } catch (JWTCreationException exception){
      //Invalid Signing configuration / Couldn't convert Claims.
  }

• Example using RS256

  RSAPublicKey publicKey = //Get the key instance
  RSAPrivateKey privateKey = //Get the key instance
  try {
      Algorithm algorithm = Algorithm.RSA256(publicKey, privateKey);
      String token = JWT.create()
          .withIssuer("auth0")
          .sign(algorithm);
  } catch (JWTCreationException exception){
      //Invalid Signing configuration / Couldn't convert Claims.
  }

If a Claim couldn't be converted to JSON or the Key used in the signing process was invalid a JWTCreationException will raise.

Verify a Token

You'll first need to create a JWTVerifier instance by calling JWT.require() and passing the Algorithm instance. If you require the token to have specific Claim values, use the builder to define them. The instance returned by the method build() is reusable, so you can define it once and use it to verify different tokens. Finally call verifier.verify() passing the token.

• Example using HS256

  String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
  try {
      Algorithm algorithm = Algorithm.HMAC256("secret"); //use more secure key
      JWTVerifier verifier = JWT.require(algorithm)
          .withIssuer("auth0")
          .build(); //Reusable verifier instance
      DecodedJWT jwt = verifier.verify(token);
  } catch (JWTVerificationException exception){
      //Invalid signature/claims
  }

• Example using RS256

  String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
  RSAPublicKey publicKey = //Get the key instance
  RSAPrivateKey privateKey = //Get the key instance
  try {
      Algorithm algorithm = Algorithm.RSA256(publicKey, privateKey);
      JWTVerifier verifier = JWT.require(algorithm)
          .withIssuer("auth0")
          .build(); //Reusable verifier instance
      DecodedJWT jwt = verifier.verify(token);
  } catch (JWTVerificationException exception){
      //Invalid signature/claims
  }

If the token has an invalid signature or the Claim requirement is not met, a JWTVerificationException will raise.

String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
try {
    DecodedJWT jwt = JWT.decode(token);
} catch (JWTDecodeException exception){
    //Invalid token
}

Usage

Pick the Algorithm

The Algorithm defines how a token is signed and verified. It can be instantiated with the raw value of the secret in the case of HMAC algorithms, or the key pairs or KeyProvider in the case of RSA and ECDSA algorithms. Once created, the instance is reusable for token signing and verification operations.

When using RSA or ECDSA algorithms and you just need to sign JWTs you can avoid specifying a Public Key by passing a null value. The same can be done with the Private Key when you just need to verify JWTs.

Using static secrets or keys:

//HMAC
Algorithm algorithmHS = Algorithm.HMAC256("secret"); //use more secure key

//RSA
RSAPublicKey publicKey = //Get the key instance
RSAPrivateKey privateKey = //Get the key instance
Algorithm algorithmRS = Algorithm.RSA256(publicKey, privateKey);

Note: How you obtain or read keys is not in the scope of this library. For an example of how you might implement this, see this gist.