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
- Signed / encrypted tokens, such as bearer access tokens in OAuth 2.0 or OpenID Connect identity tokens;
- Self-contained API keys, with optional revocation;
- Protecting 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();
For Java 7+ :
<dependency> <groupId>com.nimbusds</groupId> <artifactId>nimbus-jose-jwt</artifactId> <version>4.15</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
|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 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|
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.
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.
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.
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.
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.
The library has received numerous contributions and is now on the way to have all standard JWAs fully implemented. You’re welcome to join us in this undertaking.
- Axel Nennker and the guys behind OpenInfoCard for providing much of the initial code.
- Justin Richer from MITRE 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.
- Connect2id QA.
- Countless other contributors of bug reports, fixes and suggestions.