Establishing Identity with OIDC and JWT¶
API Endpoints Support Bearer Tokens¶
Chronicle's API listens on HTTP endpoints that accept requests. These may
Authorization: header that provides a bearer token. Chronicle
will attempt to verify the token as a basis for establishing the user's
Chronicle identity. The API is configured by various options of the
The requestor's identity is provided to the OPA evaluator for deciding whether to process the request or to refuse because it violates the policy rules. OPA policies should be set up accordingly.
Constructing Chronicle Identity from Bearer Token Claims¶
The signature of JSON web tokens must be verifiable against a JSON Web Key Set available from the configured JWKS address URI. If a userinfo address is configured then provided tokens must be accepted by that endpoint. If either test fails then the request is refused.
If a bearer token is provided, it may be an access token or an ID token. Access tokens may be opaque but, if so, a userinfo endpoint must be configured because Chronicle must be able to extract claims for providing to the OPA evaluator. These claims may be from,
- a JSON Web Token directly provided as
- a JSON Web Token or a JSON object provided by the userinfo endpoint in
response to a token provided as
In the case of a JSON Web Token being provided by the user, and the userinfo endpoint providing further information, the claims from both sources are combined. This can be a means of including both OAuth scope (from an access token) and user identity (from the user info endpoint) among the resulting claims.
For constructing the Chronicle identity from the claims, configured field names identify the claims whose values should be used in deriving the external ID of the Chronicle user who submitted the request.
Authorization: header means that the user is regarded as
being anonymous and has no accompanying claims. Such requests may be
wholly disallowed by requiring authentication.
Anonymous users may also be disallowed by
policy rules set with OPA.
For example, with the specifics depending on the behavior and configuration settings of your authorization server,
chronicle serve-api \ --jwks-address https://auth.example.com/.well-known/jwks.json \ --userinfo-address https://auth.example.com/userinfo \ --id-claims nickname \ --require-auth \ --jwt-must-claim iss https://auth.example.com/ \ --jwt-must-claim aud https://auth.example.com/chronicle-api/ \ --jwt-must-claim azp chronicle-application-id
- requires bearer tokens to be presented with API requests
- uses the fetched
jwks.jsonto verify JWT signatures
- uses the
userinfoendpoint to obtain claims associated with the token
- uses value of the
"nickname"field among the claims to derive the external ID of the authenticated Chronicle user
- rejects any requests that do not include an
Authorization:header with a bearer token
- rejects any tokens that lead to JWT claims that do not include those specified.
That last constraint relating to the
azp claims ensures that
the presented token's claims were asserted by the expected authorization
server and are intended for Chronicle to use. Those claims may also be checked
by OPA policy rules.
Note that the various URIs, etc. in this example can all be set in environment
variables instead. This can make deployments easier to manage. See the
--help text for details. For instance, the first option can be set with
JWKS_URI=https://auth.example.com/.well-known/jwks.json and the last line
JWT_MUST_CLAIM_AZP=chronicle-application-id. Note that the latter's
value would be chosen in the settings by which the Chronicle application is
registered in the authorization server's configuration.