JOSE articles

JSON Web Tokens (JWT) with Java 6

Posted on 2016-01-19

You want to develop with JSON Web Tokens (JWT), but your Java project is still stuck in 2006? We’ve got good news for you: support for Java 6 was restored in the latest release of the Connect2id library for JWT signing and encryption.

From version 4.11.2 on you’ll be able to use with library with Java 6. To do that just add the jdk16 qualifier to the Maven coordinates:

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>nimbus-jose-jwt</artifactId>
    <classifier>jdk16</classifier>
    <version>[ version ]</version>
</dependency>

where [ version ] should be the latest stable release.

The current stable release is 4.11.2.

You can find more information in the download section of the JWT library.

Why choose the Connect2id library for JWTs?

  • It’s got complete algorithm support - signing, encryption, integration with JCA providers and HSMs - you name it.

  • Huge test suite, and soon a comprehensive benchmarking suite too, so you can make an informed decision when crypto performance is critical for your project.

  • Comprehensive JavaDocs where every single class and method is documented.

  • Tonnes of examples.

Questions? Post a comment or drop us an email.

Nimbus JOSE + JWT 4.1 adds support for JWK thumbprints

Posted on 2015-09-21

The latest 4.1 release of the Nimbus JOSE + JWT library library adds support for computing JSON Web Key (JWK) thumbprints as specified in RFC 7638.

JWK thumbprints are intended to provide unique hashes of RSA, EC and shared secret key material. These may for example be used as key ID (kid) header parameters in JWS and JWE objects. OpenID Connect also uses them for self-issued identity providers.

Example usage:

// Create or parse RSA JWK
RSAKey rsaJWK = new RSAKey.Builder(...).build();

// SHA-256 is the default hash for JWK thumbprints
Base64URL thumbprintSHA256 = rsaJWK.computeThumbprint();

// The hash algorithm may be specified explicitly
Base64URL thumbprintSHA1 = rsaJWK.computeThumbprint("SHA-1");

The thumbprints are returned as a BASE64URL encoded byte array.

To get the string representation of the BASE64URL:

String b64URLString = thumbprintSHA256.toString();

To get the underlying byte array:

byte[] bytes = thumbprintSHA256.decode();

To get the thumbprint as a big integer:

BigInteger bigInt = thumbprintSHA256.decodeToBigInteger();

Download

Update 2015-09-21 The original thumbprint routine for octet sequence keys contained a bug which was fixed in 4.1.1. Thanks to Brian Campbell for spotting this.

The Maven Dependency for the 4.1.1 release:

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

For other methods check out the downloads page.

Feedback

Leave your comments below or contact Connect2id support.

Fourth release candidate of Nimbus JOSE + JWT 4.0

Posted on 2015-08-24

The Nimbus JOSE + JWT library library makes another step towards the long-awaited 4.0 release, bringing a bag full of improvements, such as full coverage of the standard JWS / JWE algorithms and a robust framework for processing JWT / JOSE objects, based on the security recommendations for key selection, which developers tend to miss.

So what’s in the new RC 4?

Immutable JWTClaimsSet

This makes it safer to pass the JWT claims set around your application, before the token is put together and signed, or after it’s processed by the recipient. The ReadOnlyJWTClaimsSet interface intended to prevent modification is no longer needed and has been removed.

With all the setters gone now, a JWTClaimsSet constructed with the help of a builder:

JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
     .subject("joe")
     .expirationDate(new Date(1300819380 * 1000l)
     .claim("http://example.com/is_root", true)
     .build();

Simplified processing framework

The framework for processing objects and tokens secured by JOSE was simplified. The optional conversion of the payload or JWT claims set to an application-specific class was factored out to a separate interface called PayloadTransformer for generic JOSE and JWTClaimsSetTransformer for JWTs.

Example:

public class MyPayloadExtractor implements PayloadTransformer<MyClass>() {
    @Override
    public MyClass transform(Payload payload) {

        // Extract application specific object from payload data 
        // encoded as JSON, XML, base64, etc.
        return MyPayloadExtractor.parse(payload.toString());
    }
};

Then, every time you receive a JOSE-secured object that is successfully verified and / or decrypted, simply call the Payload.toType method with your transformer:

// Create payload extractor, should be thread-safe
PayloadTransformer myPayloadExtractor = new MyPayloadExtractor()

Payload payload;

try {
    payload = myJOSEProcessor.process(joseObject, securityCtx);
} catch (BadJOSEException e) {
    // JOSE object rejected due to bad signature or failed integrity check
}

MyClass obj = payload.toType(myPayloadExtractor);

Want to try out the 4.0 release before it becomes final?

The Maven Dependency for the 4.0 release candidate one:

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

For other methods check out the downloads page.

Feedback

Comments or concerns? Just let us know, by dropping a note below or writing to us.

First release candidate of Nimbus JOSE + JWT 4.0

Posted on 2015-06-30

The fourth release of the Nimbus JOSE + JWT library introduces a comprehensive framework for developers to process web tokens securely and safely, something that few other libraries have tackled.

The framework is based on the key identification and key selection recommendations of the JOSE standard (as per RFC 7115). They basically work like this:

  1. Identify key candidates for verifying / decrypting the token, based on application-specific parameters included in the JOSE header and other contextual information, such as its sender or the channel.

  2. Only then have the token verified / decrypted, by having a JWS verifier / JWT decrypter for the appropriate algorithm created. If there is a mismatch between the cryptographic algorithm of the selected key and the algorithm of the token, the token is rejected.

  3. Finally, verify the token claims, again according to the rules of the application, e.g. by checking whether the issuer (iss claim) is accepted.

This framework should save developers from common pitfalls that compromise security, such as accepting alg:none tokens without sufficient checks of their context (e.g. whether they are received over a TLS/SSL channel) or using solely the alg header parameter to kick start verification / decryption.

For more information see the com.nimbusds.jwt.proc JavaDocs.

Other highlights of the 4.0 release?

  • All internal cryptography operations now use the standard JCA interfaces. The hard dependency on BouncyCastle has been removed.
  • The JWS signers / verifiers and JWE encrypters / decrypters can be set with specific JCA providers for all or selected operations.
  • Support for password-based JWE algorithms PBES2-HS256+A128KW, PBES2-HS384+A192KW and PBES2-HS512+A256KW.
  • Support for Elliptic Curve Diffie-Hellman JWE algorithms ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW.
  • Numerous other improvements.

Want to try out the 4.0 release before it becomes final?

The Maven Dependency for the 4.0 release candidate one:

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

For other methods check out the downloads page.

Feedback

We’ll be delighted to hear what you think, particularly of the new JWT processing framework.