bearertoken

The bearer token core microservice issues long-lived JWTs signed with Ed25519 keys for external actor authentication. These tokens are typically returned to end users after successful authentication and presented on subsequent requests via the Authorization: Bearer header or an Authorization cookie.

Token Minting

The Mint endpoint signs a JWT with a given set of claims. The token’s lifetime is controlled by the AuthTokenTTL configuration property (default 720h / 30 days).

The minted token includes several critical claims that are set automatically and cannot be overridden:

Claims Transformation

Claims transformers can be registered to enrich the token with additional claims before signing. Transformers are called in the order they were added and mutate the claims map in place. They cannot override the critical claims listed above, which are set after transformation.

bearertoken.NewService().Init(func(svc *bearertoken.Service) error {
    err := svc.AddClaimsTransformer(func(ctx context.Context, claims jwt.MapClaims) (err error) {
        claims["welcome"] = true
        return nil
    })
    return err
})

Transformers must be registered during initialization, before the service starts.

Key Management

Unlike the access token service which uses ephemeral in-memory keys, the bearer token service uses configured Ed25519 private keys (in PEM or raw base64 format). Two keys can be active simultaneously - PrivateKey and AltPrivateKey - to enable graceful key rotation. Tokens are always signed with the primary key; the alternative key is only used to continue verifying tokens signed before rotation.

In LOCAL and TESTING deployments, a key is auto-generated if none is configured. In LAB and PROD deployments, a key must be explicitly configured.

The JWKS endpoint exposes the corresponding public keys in standard JWKS format, enabling external systems to verify tokens issued by this service.

Token Exchange

On each incoming request, the HTTP ingress proxy looks for a bearer token, verifies its signature against the issuer’s JWKS endpoint, and exchanges it for a short-lived access token. The original iss of the bearer token is preserved in the access token’s idp claim.

Configuration