JSON Web Key (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);
- 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.