or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdio-utilities.mdjwt-operations.mdsecurity-jwk.mdtypes.md
tile.json

tessl/maven-io-jsonwebtoken--jjwt-api

JJWT API - JSON Web Token library API for Java and Android

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.jsonwebtoken/jjwt-api@0.12.x

To install, run

npx @tessl/cli install tessl/maven-io-jsonwebtoken--jjwt-api@0.12.0

index.mddocs/

JJWT API

JJWT API is the core API module of the JJWT (Java JWT) library, providing interfaces and contracts for creating and verifying JSON Web Tokens (JWTs) and JSON Web Keys (JWKs) on the JVM and Android platforms. This is a pure Java implementation based exclusively on JOSE Working Group RFC specifications including JWT (RFC 7519), JWS (RFC 7515), JWE (RFC 7516), JWK (RFC 7517), and related standards.

Package Information

  • Package Name: io.jsonwebtoken:jjwt-api
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.6</version>
</dependency>

Core Imports

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.JwtParser;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jws;

For security and key management:

import io.jsonwebtoken.security.Keys;
import io.jsonwebtoken.security.Jwks;

For IO utilities:

import io.jsonwebtoken.io.Encoders;
import io.jsonwebtoken.io.Decoders;

Basic Usage

Creating a JWT

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import javax.crypto.SecretKey;
import java.util.Date;

// Generate a secure key for HMAC-SHA algorithms
SecretKey key = Keys.secretKeyFor(Jwts.SIG.HS256);

// Create a JWT
String jwt = Jwts.builder()
    .subject("user123")
    .issuer("myapp")
    .expiration(new Date(System.currentTimeMillis() + 3600000)) // 1 hour
    .claim("role", "admin")
    .signWith(key)
    .compact();

System.out.println(jwt);

Parsing and Validating a JWT

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jws;

// Parse and verify the JWT
Jws<Claims> jws = Jwts.parser()
    .verifyWith(key)
    .build()
    .parseSignedClaims(jwt);

// Access claims
Claims claims = jws.getPayload();
String subject = claims.getSubject();
String role = claims.get("role", String.class);

System.out.println("Subject: " + subject);
System.out.println("Role: " + role);

Architecture

JJWT API follows a clean separation of concerns with several key components:

  • Factory Classes: Jwts, Keys, Jwks provide entry points and standard algorithm instances
  • Builder Pattern: Extensive use throughout for JWT construction (JwtBuilder) and parser configuration (JwtParserBuilder)
  • Type Safety: Generic interfaces ensure compile-time validation and prevent runtime errors
  • Immutability: All parsed tokens, claims, and headers are immutable value objects
  • Standards Compliance: Full implementation of JOSE specifications with comprehensive algorithm support

Capabilities

JWT Operations

Core JWT building, parsing, and validation functionality including support for signed (JWS) and encrypted (JWE) tokens.

// JWT Builder Factory
public static JwtBuilder builder();

// JWT Parser Factory  
public static JwtParserBuilder parser();

// Claims Builder Factory
public static ClaimsBuilder claims();

// Header Builder Factory
public static HeaderBuilder header();

JWT Operations

Security and JWK Management

Comprehensive key management, JSON Web Key (JWK) support, and cryptographic algorithm interfaces for secure JWT operations.

// Key Utilities
public static SecretKey hmacShaKeyFor(byte[] bytes);
public static SecretKey secretKeyFor(SignatureAlgorithm alg); // deprecated but available
public static KeyPair keyPairFor(SignatureAlgorithm alg); // deprecated but available
public static Password password(char[] password);

// Key Builders
public static SecretKeyBuilder builder(SecretKey key);
public static PrivateKeyBuilder builder(PrivateKey key);

// JWK Factory Methods
public static DynamicJwkBuilder<?, ?> builder();
public static JwkParserBuilder parser();
public static JwkSetBuilder set();
public static JwkSetParserBuilder setParser();

Security and JWK Management

IO Utilities

Encoding, decoding, and serialization utilities for Base64/Base64URL operations and custom JSON processing.

// Standard Encoders (from Encoders class)
public static final Encoder<byte[], String> BASE64 = Encoders.BASE64;
public static final Encoder<byte[], String> BASE64URL = Encoders.BASE64URL;

// Standard Decoders (from Decoders class)
public static final Decoder<CharSequence, byte[]> BASE64 = Decoders.BASE64;
public static final Decoder<CharSequence, byte[]> BASE64URL = Decoders.BASE64URL;

IO Utilities

Types and Interfaces

Core JWT types including Claims, Headers, and token interfaces that represent parsed JWT content.

// Core JWT Interface
public interface Jwt<H, P> {
    H getHeader();
    P getPayload();
    <T> T accept(JwtVisitor<T> visitor);
}

// Claims Interface  
public interface Claims extends Map<String, Object> {
    String getIssuer();
    String getSubject();
    Set<String> getAudience();
    Date getExpiration();
    // ... other standard claims
}

Types and Interfaces

Standard Algorithms

JJWT API provides constants for all standard JOSE algorithms:

Signature Algorithms (Jwts.SIG)

  • HMAC: HS256, HS384, HS512
  • RSA: RS256, RS384, RS512, PS256, PS384, PS512
  • ECDSA: ES256, ES384, ES512
  • EdDSA: EdDSA (Ed25519, Ed448)

Encryption Algorithms (Jwts.ENC)

  • AES-GCM: A128GCM, A192GCM, A256GCM
  • AES-CBC: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512

Key Management Algorithms (Jwts.KEY)

  • Direct: DIRECT
  • AES Key Wrap: A128KW, A192KW, A256KW
  • RSA: RSA1_5, RSA-OAEP, RSA-OAEP-256
  • ECDH: ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW
  • PBES2: PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW

Compression Algorithms (Jwts.ZIP)

  • DEFLATE: DEF
  • GZIP: GZIP