Key generation

Prepackaged keys

Both the MITREid Connect server webapp and the Simple Web App client come pre-packaged with public/private RSA key pairs, found in the keystore.jwks file included in each project's src/main/resources/ directory. Since these keys are the same for every clone of the repository, they are not suitable for use in a deployed system and MUST be replaced by newly generated keys.

Generating a public/private keypair

For testing purposes, you can use the Online JSON Web Key Generator.

You can use the JSON Web Key Generator project to generate a JSON Web Key suitable for your installation.

To generate a key, run java -jar json-web-key-generator-0.1-SNAPSHOT-jar-with-dependencies.jar. Several other arguments are defined which may be required depending on your key type:

 -a Algorithm (optional)
 -c Key Curve, required for EC key type. Must be one of P-256, P-384, P-521
 -i Key ID (optional) 
 -p Display public key separately 
 -s Key Size in bits, required for RSA and OCT key types. Must be an integer divisible by 8 
 -S wrap output in a JWK Set
 -t Key Type, one of: RSA, oct, EC 
 -u Usage, one of: enc, sig (optional)

The most common settings are for an RSA key pair of size 1024 wrapped in a key set with a key identifier, such as rsa1:

java -jar json-web-key-generator-0.2-SNAPSHOT-jar-with-dependencies.jar -t RSA -s 1024 -S -i rsa1

This will output to the console a key like the following (but with a different key each time):

{
  "keys": [
    {
      "d": "bj_wcFHzrMVSTQJV0-DO7S7kR7z4nW3b0EyPsFrRVuzb4Vyb_G_tmcxgHG3l31V4IXH70DOYlB3FldNC0hKenNuCb4qoSZbgZxrfX9yixESIl0V5jErDXUsHau8nQN60CPivmnv535ySP8O8b1REba1gKJBx-sYhkm83jN-AFxE",
      "e": "AQAB",
      "n": "it4yc9J1iTP_FiOMF6ExWpqCcinQKJLm5K4nQeXh4zBJC6iBvU_b6hDdpYdH5O-bvedCA7T2OOX0yjjZu5Zqx7gYMxF2707_2McmPnLQu46oVQGJATaE-ZMe-hq1U4rnsB5CVeiGc2BG1FNEHDygDf-JhIJtn4jTNg3wO55jcxE",
      "kty": "RSA",
      "kid": "rsa1"
    }
  ]
}

This JSON object is a JSON Web Key Set can be copied and pasted directly into a keystore.jwks file for use by the MITREid Connect JWKSetKeyStore class used in both the client and server.

Installing the key into a server

The server configuration uses the crypto-config.xml file to define the keys used by the server. The default configuration looks like this:

<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">

	<bean id="defaultKeyStore" class="org.mitre.jose.keystore.JWKSetKeyStore">
		<property name="location" value="classpath:keystore.jwks" />
	</bean>
	
	<bean id="defaultsignerService" class="org.mitre.jwt.signer.service.impl.DefaultJWTSigningAndValidationService">
		<constructor-arg name="keyStore" ref="defaultKeyStore" />
		<property name="defaultSignerKeyId" value="rsa1" />
 		<property name="defaultSigningAlgorithmName" value="RS256" />
	</bean>

	<bean id="defaultEncryptionService" class="org.mitre.jwt.encryption.service.impl.DefaultJWTEncryptionAndDecryptionService">
		<constructor-arg name="keyStore" ref="defaultKeyStore" />
		<property name="defaultAlgorithm" value="RSA1_5" />
		<property name="defaultDecryptionKeyId" value="rsa1" />
		<property name="defaultEncryptionKeyId" value="rsa1" />
	</bean>

</beans>

The defaultKeyStore bean points to a file on disk that stores the public and private key pair in JWKS (JSON) format, such as the one generated above or included in the demo keystore.jwks file. This bean automatically loads the contents of the file at startup and creates a key set that can be plugged into other services. To replace the set of keys, either override the keystore.jwks file and replace its contents with a new key, or override the crypto-config.xml file and point this bean's location parameter to a different keystone file somewhere else on disk, such as /etc/mitreid-connect/keystore.jwks.

The defaultsignerService and defaultEncryptionService beans use the keys from the defaultKeyStore to create a set of signer/validator and encrypter/decrypter services based on those keys. These services are used in the creation of ID Tokens, access tokens, JWT-formatted outputs from the UserInfo endpoint, and processing of signed and encrypted Request Objects. The keys are also fed into the JWK publication endpoint, which publishes the public key portion of the server's JWK at ${issuer}/jwk.