Server JWK set

The Connect2id server needs to be supplied with at least one cryptographic key to secure the tokens that it issues:

• An RSA public / private key pair. The server will use the private RSA key to sign the issued ID tokens and other objects that require that. The public RSA key is published at a well-known URL so that client applications can download it in order to verify the ID tokens and other signed objects received from the server.

• An optional AES key. This key will enable the server to apply encryption over the signed access tokens (JWT), providing confidentiality of the token content while in transit. This AES key must be shared with all servers which are expected to consume encrypted access tokens. If encryption of the JWT access tokens is not required this key can simply be omitted.

The server keys must be stored in JSON Web Key Set (JWK set) format in the following file:

WEB-INF/jwkSet.json

Important

Before you put the Connect server in production you must generate a new JWK set and put it in place of the sample JWK set that comes with the original installation package. The private RSA key must never be disclosed to other parties.

How to generate an RSA JWK

We suggest you use the JWK generator utility for that, by invoking it with the following parameters:

java -jar json-web-key-generator.jar -t RSA -s 2048 -i 1 -u sig -S

The JWK must be of type RSA and the recommended size is 2048 bits. It must also include a key identifier (a serial number, e.g. “1”, or the issue date, e.g. “2014-01-31”). It is also suggested the key use is set to “sig” (for signature).

The above command will then output a JWK set similar to this:

{
  "keys": [
    {
      "d": "Y5ULK-bLRqKAg6FcuDx4HCQmnMYUv67IQ394KBmw6F-LbdbMhNyn6UH2RAr4Wkg-TL0QXZbfuOdvvE8ZlGeWJxCGx2XOzO1wQT12mhNTD1S9NtrD_wQMc34sE6Qy5JK2CE-tWzPRT_cKzWXEJGsR0FWHphUjZOg7-vfAgPYZaZ7rptdgtq3mEs45MiURVx7DBgu5AH2x0R-s37wtR1Xw9Vx1tD6ScGl7sMu7RWerDbkkfuAUSnON_8lHzHt_GvWYI3za4KiWRH5HeYVACQ3nBrnKju_kMp9lLEGC6pgbLkthnvjf0KjMcUoKrRMKKbENhyzwFcZ6pZAtdUg-Ec3AYQ",
      "e": "AQAB",
      "n": "j37Y-Fmx2Pr9xCHXhBWvDRaXobvpikF2Nd2J_FoK8U5SlMebmqrEwddegw4OoWbBcTfcK9UMiK7mOYH7xpIxPmXyUl_ByMLT-0gTLhq-KhzsZ3SxoUqVThF6-x8XJ8DiBYO3RUSfZ3xwQwHtlXdhg6hk-iUaArYBEKGhp8R75d4w6gFHXnSzgY_llxwU7dBFUgk6H1CbBK1ozmOP5xzgnSovYt5PEetwfHjbSm_q1yFd9AuwT5QgFQhmB2jJH9rdL_W4zf8U71a3tuN-fG3LmXc2jtuDMg5LAVjzaXtPX0kQKH8_88qER1UeNfa3ceJgCfvr_EVt8PkIkh8mhB4AbQ",
      "kty": "RSA",
      "use": "sig",
      "kid": "1"
    }
  ]
}

Use it to replace the sample WEB-INF/jwkSet.json file, then restart the server.

The Connect2id server performs a check of the JWK set during startup. If a problem is found with the JWK the server will output an error message to the log and abort on the spot.

RSA JWK roll-over

To facilitate key rollover, generate a new RSA JWK with a different identifier and append it to the existing JWK set (the “keys” JSON array).

How to generate an AES JWK

The shared AES key for applying encryption to the access tokens is called octet sequence key in JWK spec.

You can choose between three AES key lengths:

• 128-bit AES key
• 192-bit AES key
• 256-bit AES key

A 128-bit AES key is sufficient for most applications.

To generate a 128-bit AES key:

java -jar json-web-key-generator.jar -t oct -s 128 -i 2 -u enc

The JWK will appear similar to this:

{
  "kty": "oct",
  "use": "enc",
  "k": "YHvpjkLXzr6Oj90sImKIyg",
  "kid": "2"
}

Append it to your existing JWK set with the RSA key pair in it like this:

{
  "keys": [
    {
      "d": "Y5ULK-bLRqKAg6FcuDx4HCQmnMYUv67IQ394KBmw6F-LbdbMhNyn6UH2RAr4Wkg-TL0QXZbfuOdvvE8ZlGeWJxCGx2XOzO1wQT12mhNTD1S9NtrD_wQMc34sE6Qy5JK2CE-tWzPRT_cKzWXEJGsR0FWHphUjZOg7-vfAgPYZaZ7rptdgtq3mEs45MiURVx7DBgu5AH2x0R-s37wtR1Xw9Vx1tD6ScGl7sMu7RWerDbkkfuAUSnON_8lHzHt_GvWYI3za4KiWRH5HeYVACQ3nBrnKju_kMp9lLEGC6pgbLkthnvjf0KjMcUoKrRMKKbENhyzwFcZ6pZAtdUg-Ec3AYQ",
      "e": "AQAB",
      "n": "j37Y-Fmx2Pr9xCHXhBWvDRaXobvpikF2Nd2J_FoK8U5SlMebmqrEwddegw4OoWbBcTfcK9UMiK7mOYH7xpIxPmXyUl_ByMLT-0gTLhq-KhzsZ3SxoUqVThF6-x8XJ8DiBYO3RUSfZ3xwQwHtlXdhg6hk-iUaArYBEKGhp8R75d4w6gFHXnSzgY_llxwU7dBFUgk6H1CbBK1ozmOP5xzgnSovYt5PEetwfHjbSm_q1yFd9AuwT5QgFQhmB2jJH9rdL_W4zf8U71a3tuN-fG3LmXc2jtuDMg5LAVjzaXtPX0kQKH8_88qER1UeNfa3ceJgCfvr_EVt8PkIkh8mhB4AbQ",
      "kty": "RSA",
      "use": "sig",
      "kid": "1" },
    {
      "kty": "oct",
      "use": "enc",
      "k": "YHvpjkLXzr6Oj90sImKIyg",
      "kid": "2" }
  ]
}

You will now have a JWK set consisting of one RSA key pair and one AES key. Observe that the key IDs don’t collide.

Assistance

Should you need help with setting up your JWK set, get in touch with Connect2id support.