Configure JWTs

VaultCode exposes a REST API to interact with it. This guide explains how to restrict access to the REST API using JSON Web Tokens (JWTs).

JWTs protect the entire VaultCode REST API (except the documentation endpoints, such as /swagger-ui/index.html). JWTs can be used in combination with API keys; the two methods are complementary.

Configure

In the application-xyz.yml configuration file, the vaultcode.jwt section contains the relevant definitions. Add the JWT secret and load the edited application-xyz.yml to the container.

vaultcode:
  # Other lines omitted

  jwt:
    secret: "a-string-secret-at-least-256-bits-long"

The secret must be at least 256 bits long. VaultCode uses this symmetric secret to verify the MAC of the JWTs that it receives.

Generate a JWT

You can use any external tool to generate a JWT token. For testing purposes, https://www.jwt.io/ is a useful tool. In production, keep your JWT secret confidential.

To be accepted by VaultCode, a token must fulfill the following requirements:

• Uses HS256 as the MAC/signature algorithm. The MAC must verify using the configured secret.
• Contains iat (issued at) and exp (expires) claims. The current time must lie within this range.

Test

When making requests to the REST API, pass a valid JWT in the Authorization HTTP header field.

For example, to fetch VaultCode's public keys:

JWT=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NzIzNjY0MDAsImV4cCI6MTc3NDk1ODQwMH0.u1gBMb5PQtCf6wNBXrLNI36n20NA5K1DckDpnUjiO24

curl "https://demo-vaultcode.securosys.com/api/v1/get_public_key" --header "Authorization: Bearer $JWT"

You can verify that requests without a valid JWT are now rejected:

{"errorCode":617,"reason":"res.error.invalid.access.token","message":"Access Token in authorization header is required"}

{"errorCode":617,"reason":"res.error.invalid.access.token","message":"Token processing failed"}