# AuxData block

The `auxData` block configures the auxiliary data sources that can be referenced in policy conditions.

## JWT

Cerbos supports reading claims from a JWT issued by an authentication system. This helps reduce the boilerplate on the client side to extract the claims from a JWT and add them as attributes to the Cerbos API request. (See [The Cerbos API](https://docs.cerbos.dev/cerbos/latest/api/) and [Auxiliary Data](https://docs.cerbos.dev/cerbos/latest/policies/conditions#auxdata) for more information on how to craft the API request and access the JWT claims in policies.)

In order to verify the JWT, the Cerbos instance must have access to the appropriate keysets. They can be fetched from a URL or read from the local file system. Verification involves checking that the signature is valid and that the token has not expired.

|     |     |
| --- | --- |
|  | Although Cerbos verifies JWTs, it’s intended as a convenience rather than an authoritative check. We recommend that the tokens are independently verified at the gateway or application level before being sent to the PDP. The verification at the PDP is purely a precaution against tampering in-flight, which should not be possible in a production deployment where TLS is enforced between the application and the PDP. |

### Using multiple keysets

```yaml
auxData:
  jwt:
    keySets:
      - id: ks1 # Unique ID that can be used in API requests to indicate the keyset to use to verify a particular token.
        remote: # Fetch from a JWKS URL.
          url: https://domain.tld/.well-known/keys.jwks
      - id: ks2
        remote:
          url: https://other-domain.tld/.well-known/keys.jwks
          refreshInterval: 1h # Explicitly set the refresh interval.
      - id: ks3
        local: # Load from a local file
          file: /path/to/keys.jwks
      - id: ks4
        local: # Load from a base64-encoded key data defined inline.
          data: BASE64-ENCODED-KEY-DATA
      - id: ks5
        local:
          file: /path/to/keys.pem
          pem: true # Treat the file (or data) as PEM.
```

|     |     |
| --- | --- |
|  | When multiple keysets are defined in the configuration file, all API requests _must_ include the keyset ID along with the JWT. When only a single keyset is defined in the configuration, then the keyset ID can be dropped from the API requests. |

When keysets are fetched from a `remote` source, if the `refreshInterval` is not defined in the configuration, Cerbos will respect the `Cache-Control` and `Expiry` headers returned from the remote source when determining the refresh interval. If none of these data points are available, then the default refresh interval is one hour.

You can disable JWT verification by setting `disableVerification` to `true`. When verification is disabled, Cerbos will not perform cryptographic verification of the JWT but the `exp` and `nbf` claims are still checked to ensure that the token is valid. You can configure the acceptable time skew for those claims by setting `acceptableTimeSkew` to a positive time duration.

|     |     |
| --- | --- |
|  | Don’t disable JWT verification unless you are certain that the token cannot be tampered with before it reaches the PDP. Similarly, it’s not recommended to set `acceptableTimeSkew` to more than a few seconds to prevent replay attacks. |

```yaml
auxData:
  jwt:
    disableVerification: true
    acceptableTimeSkew: 2s
```

Some legacy authentication systems have key sets that do not contain `alg` or `kid` fields. Not having these fields defined is a security risk and the default behaviour of Cerbos is to fail the parsing of JWT. If you are aware of the risks and still want to enable those tokens to be parsed, set the `optionalAlg` and `optionalKid` options.

```yaml
auxData:
  jwt:
    keySets:
      - id: default
        remote:
          url: https://domain.tld/.well-known/keys.jwks
        insecure:
          optionalAlg: true # Set to true only if the keyset doesn't have an alg field
          optionalKid: true # Set to true only if the keyset doesn't have a kid field
```