Framework For Minting JWS Objects And Signed JWTs - Connect2id

Skip to content

• Products
• Nimbus JOSE + JWT
• Examples
• JWS minting framework

Nimbus JOSE + JWT

• Overview
• JWS with HMAC protection
• JWS with RSA signature
• JWS with EC signature
• JWS with EdDSA / Ed25519
• JWS with JSON serialisation
• JWT with HMAC protection
• JWT with RSA signature
• JWT with EC signature
• JWT with ES256K signature
• JWT with EdDSA / Ed25519 signature
• JWS with unencoded payload
• JWS with Android biometric prompt
• PS256 with BouncyCastle FIPS
• JWS with Google Cloud KMS
• JWS with Google Cloud KMS
• JWT with RSA encryption
• JWE with shared key
• Signed & encrypted JWT
• JWE with XC20P
• JWE with preset CEK
• JWE with multiple recipients
• JWS minting framework
• Validating access tokens
• JSON entity mapping
• JOSE / JWT parsing
• Combined JOSE parsing
• Combined JWT parsing
• JWK generation
• JWK conversion
• JWK thumbprints
• JWK exp, nbf and iat times
• JWK selectors
• JWK set retrieval
• Enhanced JWK set retrieval
• JWK from PEM-encoded objects
• X.509 certificates
• Smart card and HSM use
• JWS HS256 with AWS CloudHSM

Algorithm selection guide

Command line JWK generator

Security vulnerabilities

JavaDocs

Changelog

OpenSSL key generation

JCA algorithm support

FAQ

Roadmap

Report bugs and contribute

Download

JWS minting framework

Security protocols that mint tokens often require developers to perform key selection operations. OpenID Connect provider software, like the Connect2id server, mints ID tokens that are signed with a JWS algorithm configured for each relying party. This means the OpenID provider will need to fetch a key with the matching algorithm from its store. Providers also periodically rotate their keys, a highly-recommended practice, so the selected key must also be active and not expired.

To address those needs a mini framework for minting JWS objects (of which signed JWTs are a subset) was contributed to the Nimbus JOSE+JWT library and released in version 9.8.

Features of the minting framework:

• Supports minting of generic JWS object as well as signed JWTs.

• The signing key can be sourced from an in-memory JWK set, URL, file, database, etc.

• Automatically selects a signing key that matches the JWS algorithm.

• Selects the first matching key by default, to support key rotation scenarios (this behaviour can be overridden).

• Automatically populates the JWS header with the following parameters from the selected key, if those parameters are present:

  • kid – the key identifier
  • x5t#S256 – the key SHA-256 thumbprint
  • x5t – the key SHA-1 thumbprint (deprecated)
  • x5c – the key X.509 certificate chain
  • x5u – the key X.509 certificate chain URL

• Optional SecurityContext for passing parameters to the key source.

• Thread-safe.

The framework classes can be found in the com.nimbusds.jose.mint package.

Here is an example demonstrating the minting of a signed JWT from a JWK set:

import java.util.*; import com.nimbusds.jose.*; import com.nimbusds.jose.jwk.*; import com.nimbusds.jose.jwk.gen.*; import com.nimbusds.jose.jwk.source.*; import com.nimbusds.jose.mint.*; import com.nimbusds.jose.proc.*; import com.nimbusds.jwt.*; // Generate a JWK set with two keys // RSA key pair for the JWS algorithms RS256, RS384, RS512, PS256, PS384 // and PS512 JWK rsaJWK = new RSAKeyGenerator(2048) .keyIDFromThumbprint(true) .keyUse(KeyUse.SIGNATURE) .generate(); // EC key pair with a P-256 curve for the JWS algorithm ES256 JWK ecJWK = new ECKeyGenerator(Curve.P_256) .keyIDFromThumbprint(true) .keyUse(KeyUse.SIGNATURE) .generate(); JWKSet jwkSet = new JWKSet(Arrays.asList(rsaJWK, ecJWK)); // The minter needs to be provisioned with a JWK source. The // interface allows for any kind of backend, e.g. a database or // flat file. Here the source is an in-memory JWK set. JWKSource<SecurityContext> jwkSource = new ImmutableJWKSet<>(jwkSet); // The minter is thread-safe and reusable ConfigurableJWSMinter<SecurityContext> minter = new DefaultJWSMinter<>(); minter.setJWKSource(jwkSource); // To mint a signed JWT pass the desired JWS header and claims set JWSHeader header = new JWSHeader.Builder(JWSAlgorithm.RS256) .type(JOSEObjectType.JWT) .build(); JWTClaimsSet claimsSet = new JWTClaimsSet.Builder() .subject("alice") .issuer("https://c2id.com") .issueTime(new Date()) .build(); // The minter will select a JWK that matches the JWS header // algorithm, e.g. an RSA signing key for the RS256 algorithm. If // multiple matching keys are found the first will be used for the // signing. If the JWK has parameters kid (key ID), x5u (X.509 certificate // URL), x5c (X.509 certificate chain) or x5t#256 (X.509 certificate // thumbprint) they will be copied into the JWS header, to identify the // signing key to the JWT consumer. JWSObject jwsObject = minter.mint(header, claimsSet.toPayload(), null); // Serialise the JWT System.out.println(jwsObject.serialize());

Example decoded JWT header, the kid was copied from the RSA JWK:

{ "alg" : "RS256", "typ" : "JWT", "kid" : "imTcQBlwyEP8RNryfO_ez52LWic8zZvqIXfH8lUMqYY" }

The claims set:

{ "iss" : "https://c2id.com", "sub" : "alice", "iat" : 1617812700 }

On this page