auxData block configures the auxiliary data sources that can be referenced in policy conditions.
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 and Auxiliary Data 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.
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
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
true. When verification is disabled, Cerbos will not perform cryptographic verification of the JWT but the
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.
Disabling JWT verification is not recommended because it makes the system insecure by forcing Cerbos to evaluate policies using potentially tampered data. Similarly, it’s not recommended to set
auxData: jwt: disableVerification: true acceptableTimeSkew: 2s
Cerbos maintains an in-memory cache of verified JWTs to avoid repeating the cryptographic verification step on each request. Cached tokens are still validated on each request to make sure they are still valid for use. You can increase the size of the cache by setting
auxData: jwt: cacheSize: 256 keySets: - id: default remote: url: https://domain.tld/.well-known/keys.jwks