OIDC / OAuth2

Offload JWT validation to the gateway. Nolxy verifies tokens from any OpenID Connect provider (Auth0, Google, Keycloak) before allowing traffic to your backend.

Quickstart

Add an oidcAuth block to your route to enforce that all incoming requests contain a valid JWT Bearer token issued by your provider.

{
  "oidcAuth": {
    "issuer": "https://accounts.google.com",
    "audience": "https://api.yourdomain.com",
    "requiredScopes": ["read:messages"]
  }
}

Reference

Field	Type	Default	Required	Description
issuer	string (URI)	-	Yes	The trusted Identity Provider URL. Nolxy automatically discovers endpoints via `/.well-known/openid-configuration`.
audience	string	-	Yes	The exact audience (`aud` claim) the token must have been issued for.
requiredScopes	array of strings	[]	No	List of scopes the token must contain. Fails if any are missing.
clockSkewSeconds	integer	0	No	Grace period (in seconds) for token expiration (`exp`) handling to account for clock drift.
claimHeaders	object		No	Maps JWT claims to HTTP headers automatically injected into the upstream request.

Examples

Injecting User Data via Claims

Avoid an extra database lookup in your backend by extracting information directly from the verified JWT and passing it forward as headers.

{
  "oidcAuth": {
    "issuer": "https://your-tenant.us.auth0.com",
    "audience": "https://api.yourdomain.com",
    "claimHeaders": {
      "sub": "X-User-Id",
      "email": "X-User-Email",
      "custom_role": "X-User-Role"
    }
  }
}

The upstream service will receive the request with headers like X-User-Id: auth0|123456.

Common Errors

401 Unauthorized

Missing or Expired Token

Fix: Ensure the client passes the token via the Authorization: Bearer <token> header and that the token's exp claim is valid.

403 Forbidden

Invalid Issuer or Audience, Missing Scopes

Fix: Verify the token was generated by the issuer configured on the gateway, specifically for the audience you stated, and contains all strings listed in requiredScopes.

502 Bad Gateway

OIDC Discovery Failed

Fix: Nolxy could not reach the /.well-known/openid-configuration endpoint of the issuer URL. Verify the issuer URL is public and highly available.