Authentication & OIDC

JITSudo supports two authentication methods: OIDC for web UI users and API keys for admin automation.

OIDC Authentication

JITSudo authenticates web UI users via OpenID Connect using the authorization code flow. Any OIDC-compliant provider works:

• Okta
• Auth0
• Google Workspace
• Azure AD / Entra ID
• Keycloak
• Dex (included in docker-compose for local development)

Configuration

Set the following environment variables:

OIDC_ISSUER_URL=https://your-provider.example.com
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_REDIRECT_URI=https://jitsudo.example.com/v1/auth/callback

Token Flow

1. User visits the login page
2. GET /v1/auth/providers resolves authentication methods for the user’s email domain
3. User is redirected to the OIDC provider’s authorization endpoint (scopes: openid, profile, email)
4. After authentication, the provider redirects to /v1/auth/callback with an authorization code
5. JITSudo exchanges the code for an ID token and extracts claims
6. A system JWT is issued, signed with JWT_SECRET (HMAC-SHA256), with a configurable TTL (default: 1h)

Claims Mapping

Claim	Environment Variable	Default	Description
Groups	OIDC_GROUPS_CLAIM	groups	ID token claim containing group memberships
Tenant	OIDC_TENANT_CLAIM	tenant_id	ID token claim containing tenant UUID

Per-Tenant OIDC

OIDC configuration can also be managed per-tenant via the API:

curl -X PUT https://jitsudo.example.com/v1/oidc-config \
  -H "X-API-Key: <api-key>" \
  -H "X-Tenant-ID: <tenant-uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_url": "https://tenant-provider.example.com",
    "client_id": "tenant-client-id",
    "client_secret": "tenant-secret"
  }'

API Key Authentication

For admin automation, API keys authenticate via the X-API-Key header. Keys are created per-tenant:

# Create an API key (returns the raw key once — store it securely)
curl -X POST https://jitsudo.example.com/v1/api-keys \
  -H "X-API-Key: <existing-admin-key>" \
  -H "X-Tenant-ID: <tenant-uuid>" \
  -H "Content-Type: application/json" \
  -d '{"name": "terraform-provider"}'

# List API keys (raw key is not returned)
curl https://jitsudo.example.com/v1/api-keys \
  -H "X-API-Key: <api-key>" \
  -H "X-Tenant-ID: <tenant-uuid>"

# Revoke an API key
curl -X DELETE https://jitsudo.example.com/v1/api-keys/<key-id> \
  -H "X-API-Key: <api-key>" \
  -H "X-Tenant-ID: <tenant-uuid>"

Local Authentication

JITSudo also supports local username/password authentication as a fallback when OIDC is not configured, via POST /v1/auth/login.