Skip to content
Connect2id

JWK set retrieval

The JWKSet class provides static utility methods for retrieving a JWK set from the following locations:

  • Local JSON file;
  • Remote URL;
  • Java KeyStore, including PKCS#11 key stores such as a smart card or HSM.

How to load a JWK set from a file

Just provide the name of the file where the JWK set is saved:

import com.nimbusds.jose.jwk.JWKSet;

// Load JWK set from filesystem
JWKSet localKeys = JWKSet.load(new File("my-key-store.json"));

// Load JWK set from URL
JWKSet publicKeys = JWKSet.load(new URL("https://c2id.com/jwk-set.json"));

How to load a JWK set from a URL

Provide a URL, will throw an IOException on HTTP error:


import com.nimbusds.jose.jwk.JWKSet;

// Load JWK set from URL
JWKSet publicKeys = JWKSet.load(new URL("https://c2id.com/jwk-set.json"));

There is also an extended load method for setting a precise HTTP connect or read timeout, or to limit the size of the read data. That is intended as a simple defence mechanism in case of a DoS attack against a public OpenID Connect provider or other applications which rely on key material that is supplied dynamically.

// HTTP connect timeout in milliseconds
int connectTimeout = 100;

// HTTP read timeout in milliseconds
int readTimeout = 100;

// JWK set size limit, in bytes
int sizeLimit = 10000;

// The URL
URL url = new URL("https://c2id.com/jwk-set.json")

// Load JWK set from URL
JWKSet publicKeys = JWKSet.load(url, connectTimeout, readTimeout, sizeLimit);

Check out the enhanced JWK set sourcing facility if you need rate-limiting, caching, retrial and other features.

How to load a JWK set from a Java KeyStore

Version 4.33 of the Nimbus JOSE+JWT library added a new static method which exports the keys found in a java.security.KeyStore into a JWK set. Keys that cannot be converted to a standard JWK, for example EC keys with curves other than P-256, P-384 and P-521, will be silently ignored.

Also supports PKCS#11 stores such as smart cards and HSMs; with such a key store the private keys will be represented as handles, which can then be accessed with RSAKey.toPrivateKey and ECKey.toPrivateKey.

import com.nimbusds.jose.jwk.JWKSet;
import java.io.*;
import java.security.*;

// Specify the key store type, e.g. JKS
KeyStore keyStore = KeyStore.getInstance("JKS");

// If you need a password to unlock the key store
char[] password = "secret".toCharArray();

// Load the key store from file
keyStore = keyStore.load(new FileInputStream("myKeyStore.jks"), password);

// Extract keys and output into JWK set; the secord parameter allows lookup
// of passwords for individual private and secret keys in the store
JWKSet jwkSet = JWKSet.load(keyStore, null);

Features:

  • The JWK identifier (kid) will be set from the key alias in the store.
  • For each RSA or EC JWK the following parameters will also be set:
    • The key use (use) parameter, based on the X.509 subject public key use;
    • The X.509 certificate chain (x5c) parameter;
    • The X.509 certificate SHA-1 thumbprint (x5t) parameter;
    • The private key parameters, or PKCS#11 handle, if a matching private key is found in the store and a password is provided for it.