Signing keys for JSON web tokens (JWTs) are required. It is good practice to rotate, i.e., periodically invalidate and replace them, to ensure cryptographic integrity, limit long-term exploits, etc. Since many clients cache keys from the server, we have to take into account the cache lifetime as well as the access token lifetime. Caches are updated daily. The rotation method is to issue new keys, that become valid only at the end of the cache liftime, then setting the expiration for the current keys to be the sum of the cache and access token lifetimes.
The reson is that this lets clients refresh their cache and exchange/refrsh any access tokens before the old keys are invalidated. Do remember that refresh tokens are not signed, so even though they have very long lifetimes compared to access tokens, they play no role.
You may either set the policy in the server XML file (described here), along with an initial set of keys, or create a default virtual issuer and set it there. Note that if there is an XML configuration and a VI, the VI is used. Some OA4MP installs do not use virtual issuers and have no need to set one up. The XML configuration allows for a very simple, basic configuration to do server key rotation.
| Name | Required | Default | |
| enabled | N | false | Enable key rotation? If false, then no key rotation of the server keys will occur. If overrides are allowed, virtual issuers are, however, still permitted to set them. |
| allowOverride | N | false | If virtual issuers can set their own key rotation policy. This means they may specify the grace periods for the cache and accesss token (if differnt from the |
| cacheGracePeriod | N | -1 | Keys may be cached by clients. This may be given in various units, but the default is in seconds. The policy will be set as the sum of this and the access token grace period. A value of -1 (default) means to just use the server's value. |
| atGracePeriod | N | -1 | The duration of the access token grace period if different from the one configured for the server. A value of -1 (default) means to just use the server's value. |
A typical server entry might be
<keyRotation enabled="true"
allowOverride="true"
cacheGracePeriod="24 hr"
atGracePeriod="6 hr"/>
For more details see the key rotation documentation