Nimbus JOSE + JWT
- The most popular and robust Java library for JSON Web Tokens (JWT)
- All standard signature (JWS) and encryption (JWE) algorithms are supported, including secp256k1 used in Bitcoin and Ethereum
- Open source Apache 2.0 license
Secure your tokens and APIs
- Signing and encrypting tokens, such as bearer access tokens in OAuth 2.0 and OpenID Connect identity tokens;
- Security event tokens;
- Self-contained API keys, with optional revocation;
- Stateless sessions;
- Protecting arbitrary content and messages;
- Authenticating clients and web API requests.
// 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; new SecureRandom().nextBytes(sharedKey); // Apply the HMAC to the JWS object jwsObject.sign(new MACSigner(sharedKey)); // Output to URL-safe format jwsObject.serialize();
Need more examples? We haven plenty of them!
For Java 7+ :
<dependency> <groupId>com.nimbusds</groupId> <artifactId>nimbus-jose-jwt</artifactId> <version>5.8</version> </dependency>
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, ES256P✝, ES384 and ES512|
✝ Based on the standard secp256k1 curve. Note that the JWS ES256P algorithm name and the P-256K curve name are not officially registered.
|Key management||JWE alg identifiers|
|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|
|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.
From the OAuth work group:
- JWT RFC 7519
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.
The library source code is provided under the Apache 2.0 licence.
To post bug reports and suggestions
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.
- Aleksei Doroganov for adding ES256P support based on secp256k1 ECDSA.
- Everyone on the JOSE WG at the IETF.
- Numerous other contributors of bug reports, fixes and suggestions.