Nimbus JOSE + JWT

  • The most popular and robust Java library for JSON Web Tokens (JWT)
  • Supports all standard signature (JWS) and encryption (JWE) algorithms
  • Open source Apache 2.0 licence

Secure your tokens and messages on the web

This library implements the Javascript Object Signing and Encryption (JOSE) and JSON Web Token specs (JWT), providing comprehensive yet easy to use security for

  • Signing and encrypting tokens, such as bearer access tokens in OAuth 2.0 or OpenID Connect identity tokens;
  • Event tokens;
  • Self-contained API keys, with optional revocation;
  • Stateless sessions;
  • Protecting arbitrary content and messages;
  • Authenticating clients and web API requests.

Hello, world!

// Create an HMAC-protected JWS object with some payload
JWSObject jwsObject = new JWSObject(new JWSHeader(JWSAlgorithm.HS256),
                                    new Payload("Hello, world!"));

// We need a 256-bit key for HS256 which must be pre-shared
byte[] sharedKey = new byte[32];
new SecureRandom().nextBytes(sharedKey);

// Apply the HMAC to the JWS object
jwsObject.sign(new MACSigner(sharedKey));

// Output to URL-safe format

Need more examples? We haven plenty of them!


For Java 7+ :


Go to the downloads page for Java 6 specific instructions.

Full compact JOSE and JWT support

Create, serialise and process compact-encoded:

  • Plain (unsecured) JOSE objects;
  • JSON Web Signature (JWS) objects;
  • JSON Web Encryption (JWE) objects;
  • JSON Web Key (JWK) objects and JWK sets;
  • Plain, signed and encrypted JSON Web Tokens (JWTs).

The less frequently used alternative JSON encoding is on the road map.

All standard JWS and JWE algorithms are covered

Check our awesome crypto algorithm selection guide if you’re unsure which one is the right for your app.


MAC / signature JWS alg identifiers
HMAC integrity HS256, HS384 and HS512
RSASSA-PKCS1-V1_5 signatures RS256, RS384 and RS512
RSASSA-PSS signatures PS256, PS384 and PS512
EC signatures ES256, ES384 and ES512


Key management JWE alg identifiers
RSAES-PKCS1-V1_5 encryption RSA1_5
AES key wrap encryption A128KW, A192KW and A256KW
Direct shared symmetric key encryption dir
Elliptic Curve Diffie-Hellman key agreement ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW
AES GCM key wrap encryption A128GCMKW, A192GCMKW and A256GCMKW
PBES2 key encryption PBES2-HS256+A128KW, PBES2-HS384+A192KW and PBES2-HS512+A256KW

Encryption methods JWE enc identifiers
AES/CBC/HMAC/SHA authenticated encryption A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128CBC+HS256 (deprecated) and A256CBC+HS512 (deprecated)
AES in Galois/Counter Mode (GCM) A128GCM, A192GCM and A256GCM

Compression JWE zip identifier


Key type JWK kty identifier
RSA (RFC 3447) RSA
Elliptic Curve (DSS) EC
Octet sequence (symmetric key) oct
Octet key pair (RFC 8037) OKP

Crypto is fully decoupled from the JOSE / JWT object representations

New JWA algorithms can be easily added. A set of interfaces effectively decouple the JOSE / JWT objects from the JWA crypto code for signing / verification and encryption / decryption. Multiple JCA providers, including hardware-based (smart cards and HSM), are supported. Developers are free to use the provided algorithm implementations or plug their own.


The Nimbus JOSE + JWT code comes with complete JavaDocs. Use them as your trustworthy API reference to discover the library’s many features and capabilities. You can download the JavaDocs from Maven Central, or browse them online.

Implemented specifications

From the JavaScript Object Signing and Encryption (JOSE) work group:

From the OAuth work group:

  • Web Cryptography API — W3C effort to specify a standard JavaScript API for performing crypto operations in the browser.

System requirements and dependencies

The Nimbus JOSE + JWT library works with Java 6+ and has minimal dependencies.

  • JSON Smart for highly efficient parsing and serialisation of JSON.

  • JCIP for concurrency annotations.

  • [optional] BouncyCastle can be used as an alternative crypto backend via the standard Java Cryptography Architecture (JCA) interface. Users typically resort to BouncyCastle if they run an older Java edition (6 or 7) that doesn’t support certain JWS and JWE crypto operations. See JCA algorithm support for more info.

JWK generator

A tool for generating RSA, EC and symmetric JSON Web Keys (JWKs) is also available, thanks to Justin Richer. He also hosts an online version.


The library source code is provided under the Apache 2.0 licence.

To post bug reports and suggestions

Your feedback is important. Read how to submit bug reports and suggestions. And here is a list of outstanding things that we want to do.


Development of this library was started by Connect2id in January 2012. The initial code was based on JWS/JWE/JWT crypto classes factored out of the OpenInfoCard project. A rewrite to fully decouple the JOSE + JWT object representation from the crypto implementation led to the next major 2.0 release in October 2012. Today the library is used by our OpenID Connect server and numerous other products and services in identity, messaging, mobile and finance.


  • Axel Nennker and the developers behind OpenInfoCard for providing much of the initial code.
  • Justin Richer for handling initial releases to Maven Central, JPSK support, numerous improvements, fixes and suggestions.
  • Melisa Halsband from CertiVox for implementing AES key wrap and AES GCM key wrap encryption.
  • Cedric Staub for adding explicit JCA provider interfaces.
  • Ville Kurkinen for adding initial Maven support.
  • David Ortiz for initiating RSA encryption development.
  • Quan Nguyen, Google Information Security Engineer, Project Wycheproof, for reporting Padding Oracle and integer overflow vulnerabilities in AES/CBC/HMAC decryption.
  • Juraj Somorovsky for security related reviews, improvements and suggestions.
  • Antonio Sanso for his work in investigating invalid curve vulnerabilities in JOSE implementations.
  • Lai Xin Chu for initial work on JWE.
  • Wisgary Torres from the Microsoft Xbox team for important feedback and bug reports.
  • Brian Campbell for JWT thumbprint debugging.
  • CertiVox UK for supporting the library development.
  • Casey Lee for adding a Java 6 build profile.
  • Dimitar A. Stoikov on adding support for AES ciphers with internally generated IV.
  • Everyone on the JOSE WG at the IETF.
  • Numerous other contributors of bug reports, fixes and suggestions.