Skip to main content

docs/auth.md

Metadata​

  • Purpose: Project documentation source file.
  • Domain: documentation
  • Language: md
  • Bytes: 3228
  • Lines: 78
  • Content hash (short): 26dd8f68
  • Source (start): docs/auth.md:1
  • Source (end): docs/auth.md:78

Indexed Symbols​

No indexed functions/methods detected in this file.

Markdown Headings (if applicable)​

  • H1: Authentication and Authorization (line 1)
  • H2: Modes (line 3)
  • H2: JWT verification paths (line 9)
  • H2: Required claims (line 20)
  • H2: Portal invite JWT model (GA) (line 29)
  • H2: Web operator JWT guardrails (line 40)
  • H2: Example payload (line 53)
  • H2: Public routes (line 66)
  • H2: Non-tenant routes (line 74)

Source Preview​

# Authentication and Authorization

## Modes

- `AUTH_MODE=disabled`: development mode; gateway injects a local admin auth context.
- `AUTH_MODE=jwt`: bearer JWT is required on non-public routes.
- In `staging`/`production`, `AUTH_MODE=jwt` is mandatory.

## JWT verification paths

1. HS256 shared secret:
- Set `JWT_SIGNING_SECRET`
- Used when `AUTH_JWKS_URL` is not set

2. OIDC/JWKS:
- Set `AUTH_JWKS_URL` to your identity provider JWKS endpoint
- Set `AUTH_ISSUER` and `AUTH_AUDIENCE`
- Gateway validates tokens with remote signing keys (`RS*`/`ES*` algorithms via JOSE)

## Required claims

- `sub` (required)
- `roles` (non-empty array)
- `workspaceIds` (non-empty array, use `"*"` for all)
- `exp` (required in `staging`/`production`)