# JWKS Rotation - OpenID Connect Authentication

Source: https://apereo.github.io/cas/development/authentication/OIDC-Authentication-JWKS-Rotation.html

Key rotation is when a key is retired and replaced by generating a new cryptographic key. Rotating keys on a regular basis is an industry standard and follows cryptographic best practices.

You can manually rotate keys periodically to change the JSON web key (JWK) key, or you can configure the appropriate schedule in CAS configuration so it would automatically rotate keys for you.

> **Rotation Guidance**
>
> NIST guidelines seem to recommend a rotation schedule of at least once every two years. In practice, modest CAS deployments in size and scale tend to rotate keys once every six months, either manually or automatically on a schedule.

Keys that are generated by CAS and put into the keystore carry an extra `state` parameter that indicates the lifecycle status of the assigned key. The following values are accepted lifecycle states:

| Value | Description |
| --- | --- |
| `0` | The key is active and current, used for required operations. |
| `1` | The key will be the next key used during key rotation. |
| `2` | The key is no longer used and active, and will be removed after revocation operations. |

CAS always signs with only one signing key at a time, typically the *very first key* listed and loaded from the keystore, that is deemed active and current judging by the `state` parameter. For backward compatibility, the absence of this parameter indicates that the key is active and current.

The dynamic discovery endpoint will always include both the current key and the next key, and it may also include the previous key(s) if the previous key has not yet been revoked. To provide a seamless experience in case of an emergency, client applications should be able to use any of the keys specified in the discovery document.

The following settings and properties are available from the CAS configuration catalog:

- `cas.authn.oidc.jwks.revocation.schedule.cron-expression` (Optional; type `String`): A cron-like expression, extending the usual UN*X definition to include triggers on the second, minute, hour, day of month, month, and day of week. For example, `0 * * * * MON-FRI` means once per minute on weekdays (at the top of the minute - the 0th second) or `0 0 0 * * *` means every day at midnight. * Note that when cron expressions are defined, the start delay and repeat interval settings are must be removed and set to blank.
- `cas.authn.oidc.jwks.revocation.schedule.cron-time-zone` (Optional; type `String`): A time zone for which the cron expression will be resolved. By default, this attribute is empty (i.e. the scheduler's time zone will be used).
- `cas.authn.oidc.jwks.revocation.schedule.enabled` (Optional; type `Boolean`; default `true`): Whether scheduler should be enabled to schedule the job to run.
- `cas.authn.oidc.jwks.revocation.schedule.enabled-on-host` (Optional; type `String`; default `.*`): Overrides `SchedulingProperties#enabled` property value of true if this property does not match hostname of CAS server. This can be useful if deploying CAS with an image in a statefulset where all names are predictable but where having different configurations for different servers is hard. The value can be an exact hostname or a regular expression that will be used to match the hostname.
- `cas.authn.oidc.jwks.revocation.schedule.repeat-interval` (Optional; type `String`; default `PT2M`): String representation of a repeat interval of re-loading data for a data store implementation. This is the timeout between consecutive job’s executions.
- `cas.authn.oidc.jwks.revocation.schedule.start-delay` (Optional; type `String`; default `PT15S`): String representation of a start delay of loading data for a data store implementation. This is the delay between scheduler startup and first job’s execution
- `cas.authn.oidc.jwks.rotation.schedule.cron-expression` (Optional; type `String`): A cron-like expression, extending the usual UN*X definition to include triggers on the second, minute, hour, day of month, month, and day of week. For example, `0 * * * * MON-FRI` means once per minute on weekdays (at the top of the minute - the 0th second) or `0 0 0 * * *` means every day at midnight. * Note that when cron expressions are defined, the start delay and repeat interval settings are must be removed and set to blank.
- `cas.authn.oidc.jwks.rotation.schedule.cron-time-zone` (Optional; type `String`): A time zone for which the cron expression will be resolved. By default, this attribute is empty (i.e. the scheduler's time zone will be used).
- `cas.authn.oidc.jwks.rotation.schedule.enabled` (Optional; type `Boolean`; default `true`): Whether scheduler should be enabled to schedule the job to run.
- `cas.authn.oidc.jwks.rotation.schedule.enabled-on-host` (Optional; type `String`; default `.*`): Overrides `SchedulingProperties#enabled` property value of true if this property does not match hostname of CAS server. This can be useful if deploying CAS with an image in a statefulset where all names are predictable but where having different configurations for different servers is hard. The value can be an exact hostname or a regular expression that will be used to match the hostname.
- `cas.authn.oidc.jwks.rotation.schedule.repeat-interval` (Optional; type `String`; default `PT2M`): String representation of a repeat interval of re-loading data for a data store implementation. This is the timeout between consecutive job’s executions.
- `cas.authn.oidc.jwks.rotation.schedule.start-delay` (Optional; type `String`; default `PT15S`): String representation of a start delay of loading data for a data store implementation. This is the delay between scheduler startup and first job’s execution

### Custom

It is possible to design and inject your own key rotation and revocation strategy into CAS using the following `@Bean` that would be registered in a `@AutoConfiguration` class:

```java
@Bean
public OidcJsonWebKeystoreRotationService oidcJsonWebKeystoreRotationService() {
    return new MyJsonWebKeystoreRotationService();
}
```

Your configuration class needs to be registered with CAS. [See this guide](https://apereo.github.io/cas/development/configuration/Configuration-Management-Extensions.html) for better details.
