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 messages and tokens on the web

This library implements the new JOSE and JWT specs, providing robust and easy to use security for

  • Signed / encrypted tokens, such as bearer access tokens in OAuth 2.0 or OpenID Connect identity tokens;
  • Stateless sessions;
  • Self-contained API keys, with optional revocation;
  • Protecting 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
jwsObject.serialize();

More examples?

Maven

For Java 7+ :

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>nimbus-jose-jwt</artifactId>
    <version>4.23</version>
</dependency>

Go to the downloads page for Java 6 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 crypto algorithm selection guide if you’re unsure which one is the right for your app.

JWS

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

JWE

Key management JWE alg identifiers
RSAES-PKCS1-V1_5 encryption RSA1_5
RSAES OAEP encryption RSA-OAEP, RSA-OAEP-256
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
RFC 1951 DEFLATE

JWK

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

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 (HSM), are supported. Developers are free to use the provided algorithm implementations or plug their own.

JavaDocs

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.

  • Apache Commons IO for retrieving remote JWK sets by URL.

  • [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 has hosts an online version.

Licensing

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.

History

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.

Acknowledgements

  • 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.
  • Juraj Somorovsky for security related reviews, improvements and suggestions.
  • 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.
  • Everyone on the JOSE WG at the IETF.
  • Numerous other contributors of bug reports, fixes and suggestions.