Skip to content
NocleyeNocleye Docs

Authentication

The gateway can validate signed JWT tokens before forwarding a request. A request whose token is missing or invalid gets 401 Unauthorized and never reaches the backend.

Authentication methods are defined under AuthMethods and bound by name with AuthMethod on GlobalConfig, a server or a route. The closest scope wins: route, then server, then global. Routes with no authentication method are public.

AuthMethods:
  secure-hs256-bearer:
    Mode: Bearer
    SigningMethod: HS256
    KeyRef: "file:/etc/gateway/keys/hs256.key"
    IdClaimName: sub
    RefuseOnMissing: true
    RefuseOnExpired: true


  secure-hs512-raw:
    Mode: RawHeader
    SigningMethod: HS512
    HeaderName: X-Auth-Token
    KeyRef: "env:HS512_SECRET"
    IdClaimName: sub
    RefuseOnMissing: true
    RefuseOnExpired: true


ServerRoutes:
  a-secure:
    TargetServer: svc-a
    PathPattern: /a/secure
    AuthMethod: secure-hs256-bearer

Options

Section titled “Options”
Key Required Description
Mode yes Where the token is read from: Bearer or RawHeader.
SigningMethod yes Algorithm the token must be signed with.
KeyRef yes Where the verification key comes from. See Keys.
HeaderName RawHeader only Header that carries the token.
IdClaimName no Name of the token claim that identifies the caller, e.g. sub.
Issuer no When set, the token’s iss claim must match.
Audience no When set, the token’s aud claim must contain this value.
RefuseOnMissing no Set to true to reject requests that carry no token.
RefuseOnExpired no Set to true to reject requests whose token is expired.

Set both RefuseOnMissing and RefuseOnExpired to true unless you have a reason not to. nocleye check warns when either is false.

Modes

Section titled “Modes”
Mode Token location
Bearer The Authorization header, in the form Authorization: Bearer <token>.
RawHeader The header named in HeaderName, containing the bare token, e.g. X-Auth-Token: <token>.

Signing methods

Section titled “Signing methods”
SigningMethod Algorithm Key
HS256, HS384, HS512 HMAC with SHA-2 Shared secret
RS256 RSA PEM public key
ES256 ECDSA P-256 PEM public key
EdDSA Ed25519 PEM public key, or the raw 32 byte key

A token signed with a different algorithm than the one configured is rejected.

Keys

Section titled “Keys”

KeyRef must start with env: or file::

Form Meaning
env:NAME The key is the value of the environment variable NAME.
file:path The key is the content of the file. A relative name is looked for in /etc/nocleye-beta/gateway/auths/ first, then used as given.

Keys are loaded when the gateway starts. The gateway refuses to start if a key can’t be read or doesn’t match the signing method, nocleye check does not read key files.

Caller identity

Section titled “Caller identity”

After a token is validated, the caller is identified by the claim named in IdClaimName. If IdClaimName is not set, or the token doesn’t contain the claim, the raw token is used instead. This identity is used as the key for usage control and is written to the access log as caller_id.

On routes with an authentication method, the client ID rule is not used.

Validation

Section titled “Validation”
  • An unknown Mode or SigningMethod is an error.
  • A missing KeyRef is an error. A missing HeaderName in RawHeader mode is an error.
  • Binding an authentication method that does not exist is an error.
  • Having no authentication methods at all is a warning: every route is public.