Usage of the Chronicle API can be protected using JWT by using Chronicle's command-line interface (CLI). Run
inx-chronicle --help to learn about all available options under the
All JWT interactions should be performed via HTTPS.
When a route is configured to be public, it can be accessed freely without providing a JWT. Thus, you should take care when specifying these routes, as a mis-configured route can open the application up to attacks. The only accepted special character is the wildcard (
*), which will be converted to a regex
.* and match against the original URI.
For instance, a request
GET https://localhost:XXXX/api/core/v2/milestones/by-index/10000 will check the set of public routes against the segment
Matching strings include:
Non-matching strings include:
If JWT is used, these routes should be as specific as possible to avoid accidentally exposing unintended routes.
Chronicle uses an EdDSA secret key to create tokens, which can be generated by the application at startup or provided as an identity file using the
identity_path config. Currently, this file must be a PKCS8 secret key (RFC 5208) PEM file. The location of this file can also optionally be specified using the
IDENTITY_PATH env variable, which will be overridden by the config file value. If no such file is provided, a secret key is randomly generated for use while the application is running.
Generating a Token
A special route at the root (
/login) is provided for generating a new token. This token will use the password config as well as the
jwt_expiration and the secret key. This token can be manually generated by the client, if desired, by using the same identity and claims.
Static claims used by Chronicle are:
sub (subject) claim is filled using a unique UUID, however it is not currently stored or validated by Chronicle.
Providing a Token
To provide a token when making a request, include it in an
Authorization header using the
Bearer authentication scheme.