Skip to main content

Authentication

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 API section.

All JWT interactions should be performed via HTTPS.

Public Routes

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/_milestone_s/by-index/10000 will check the set of public routes against the segment /api/core/v2/milestones/by-index/10000.

Matching strings include:

  • /api/*
  • /api/core/*/milestones/by-index/*
  • *10000

Non-matching strings include:

  • /core/v2/milestones/by-index/*
  • /api/core/v2/milestones/by-index
  • /api/core/v1/*

If JWT is used, these routes should be as specific as possible to avoid accidentally exposing unintended routes.

Keys

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:

  • iss: "chronicle"
  • aud: "api"

The 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.