Signing for OIDC

ID tokens are signed as per the JSON Web Key specification. This requires that the server supply public information about its keys so that clients may validate them. The well-known page for the service will give the location of the web key file in the jwks_uri entry. Generally you merely need to set this up on the server and clients will validate the signatures that your server creates. The configuration entry is:

Name Required Default
path Y (none) The full path to the JSON web key file. This is probably best done within CDATA tags to ensure that special characters such as blanks and slashes, are interpreted correctly.

There is one attribute and that is defaultKeyID which tells which key should be used for signing. If you have a single key, then that will be used as the default, otherwise you must specify the default key or there will be an error at boot.

An example configuration

<service name="myInstall">
    <!-- other stuff -->
    <JSONWebKey
        defaultKeyID="E80281A5CD86D1288B15A9D868586B9B">
        <path>/var/www/config/keys.jwks</path>
    </JSONWebKey>
</service>

This sets the path to the file keys.jwks in the given directory. This file contains multiple keys, so if you do not set the defaultKeyID, an error will be generated on server startup. Within that file is an entry that has a unique key identifier ("kid"): 

{"keys": [
      {
      "n": "AIptVWe86psnN3Vr4ovJZF0T0oBqlDMrpX2JcJ3g8UQ5NZG8Fugb5FD8aB6jXU98AS3IIi8ORCVsSb7lUvdFrHoZuOQ74rXrStIBSeXySOv_kSC4gJltMU2ld9sXUVbvLulFLSRoIttstacy8EZ8ULM5PaeNUuiVNQW5weQOWig0xuNhS_5nkn1ujarNitCWhI_RmGAdRjL3uJxahKqm2ZRvxnEO6ajFfb7j13HJuzw9bkGkDVY6LZRbPCCZq57geEwmbgjMN6F3m6CUSvbkvIgqqVzm7GEDlk8J4Jer8tavJ_lkiQ3J1q-CoYr38UFx4Q3s",
      "e": "AQAB",
      "alg": "RS384",
      "kid": "E80281A5CD86D1288B15A9D868586B9B",
      "use": "sig",
      "kty": "RSA",
      "d": "NuCDNB37r8iLPtynMh2D0TZzg_88hG9KyXKjhM1zZuGVNtidwbfD0oMDgrVfXEgBmMC98bEuob7H1iPl371wd9EjCOb2EVyeWHLhnoIl_y0SgmYmAj0Ki8NST2TApwUdzjUwj4SikFOdJmap5UZMUBuMfgqJtSAHixnrcDGlvh0nwt66axV5GEA6gT_gXx0V8JsGRvU5zxMVn8-0Nfeo53ao4sVqO8lwsinPgeEuDpaoTvbNtlGpw5CeYtveZpPgIgYATr6_ke8UNalax8py2zmHyswHX3CzEEuguJUfKEeHBeIyECsfRdM2z6CsDGI-a4fe-VzudYDVMUQ"
      }]
}

There may be several other entries in the file which is why the key identifier is needed. In this case, every ID token will be signed with the RSA key using 384 bits. (Note this example should not be used anywhere. Please see the next section for how to generate keys properly.) Clients may request other strengths which the server may or may not honor. Only the RSA signing algorithm is supported by OA4MP.

Creating a set of keys at the command line

The supplied command line tool (oa2-cli in the /opt/oa2/bin directory) has the ability to create a set of key. OA4MP will support RSA signing at 256, 384 and 512 bits. Using the command line tool will create keys for each of these. To use this, you will need to start the tool then use keys:

    oa2>use keys
    keys>create
      Give the file path[]:/var/www/config/keys.jwks
      create a new set of JSON web keys?[y/n]y
      JSONweb keys written
      Done!
    keys>exit
    exiting ...

In this example, you use signing and invoke the create call. This prompts you for the full path (including the file name) and then verifies that you want to create the keys. Note that if you specify an existing file, you will be asked if you want to overwrite it. The resulting file will be in JSON web key format and ready for use. You must specify this file for the server to use.

You should be sure that this file is put somewhere that is not public on your system and that the permissions allows tomcat to access it (usually this means at least that the grouop should be set to "tomcat" on unix installs. It should also be read only for all access.