OIDC Authentication

Configure OpenID Connect SSO for AllureDeck with role mapping from identity provider group claims.

Overview

AllureDeck supports two authentication methods operating simultaneously:

1. Local authentication — static admin/viewer credentials via environment variables
2. OIDC SSO — OpenID Connect with any compliant identity provider

Local auth serves as a break-glass fallback when SSO is enabled.

How It Works

AllureDeck uses the Authorization Code + PKCE flow. The entire OIDC exchange happens server-side — the frontend only provides an SSO button.

Browser                    AllureDeck API              Identity Provider
  |                              |                              |
  |-- click "Sign in with SSO" ->                              |
  |                              |-- redirect with PKCE ------->
  |                              |                              |
  |                              |<---- authorization code -----|
  |                              |                              |
  |                              |-- exchange code + verifier ->
  |                              |<---- ID token ---------------|
  |                              |                              |
  |                              |  validate token, extract claims,
  |                              |  resolve role from groups,
  |                              |  JIT-provision user record,
  |                              |  issue AllureDeck JWT cookies
  |                              |                              |
  |<-- redirect with cookies ---|                              |

Key security properties:

• PKCE (S256) on every authorization request
• State parameter encrypted with AES-GCM in an httpOnly cookie
• Nonce validated in the ID token to prevent replay attacks
• Group claims read from the signed ID token only (not userinfo endpoint)
• JIT provisioning — user records created on first login, updated on subsequent logins

Configuration Reference

All OIDC settings are provided via environment variables. Variables marked with * are required when OIDC_ENABLED=true — the server refuses to start if they are missing.

* Required when OIDC_ENABLED=true. Server refuses to start if missing.

Role Mapping

Roles are resolved from IdP group claims using highest-priority-wins:

1. If any group matches OIDC_ADMIN_GROUPS → admin
2. Else if any matches OIDC_EDITOR_GROUPS → editor
3. Else → OIDC_DEFAULT_ROLE (default: viewer)

User Lifecycle

• First login: User record created automatically (JIT provisioning) with resolved role
• Subsequent logins: Name, email, and role updated from latest token claims
• Deactivation: Set is_active=false in users table. User receives 403 on next SSO login

Provider Setup

Select your identity provider below for step-by-step configuration instructions.

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<application-client-id>
OIDC_CLIENT_SECRET=<client-secret-value>
OIDC_REDIRECT_URL=https://alluredeck.example.com/api/v1/auth/oidc/callback
OIDC_GROUPS_CLAIM=groups
OIDC_ADMIN_GROUPS=<azure-ad-group-object-id-for-admins>
OIDC_EDITOR_GROUPS=<azure-ad-group-object-id-for-editors>
OIDC_STATE_COOKIE_SECRET=<32-byte-random-string>

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://keycloak.example.com/realms/<realm>
OIDC_CLIENT_ID=alluredeck
OIDC_CLIENT_SECRET=<client-secret>
OIDC_REDIRECT_URL=https://alluredeck.example.com/api/v1/auth/oidc/callback
OIDC_GROUPS_CLAIM=groups
OIDC_ADMIN_GROUPS=alluredeck-admins
OIDC_EDITOR_GROUPS=alluredeck-editors
OIDC_STATE_COOKIE_SECRET=<32-byte-random-string>

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://accounts.google.com
OIDC_CLIENT_ID=<client-id>.apps.googleusercontent.com
OIDC_CLIENT_SECRET=<client-secret>
OIDC_REDIRECT_URL=https://alluredeck.example.com/api/v1/auth/oidc/callback
OIDC_DEFAULT_ROLE=editor
OIDC_STATE_COOKIE_SECRET=<32-byte-random-string>

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://<your-okta-domain>/oauth2/default
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
OIDC_REDIRECT_URL=https://alluredeck.example.com/api/v1/auth/oidc/callback
OIDC_GROUPS_CLAIM=groups
OIDC_ADMIN_GROUPS=alluredeck-admins
OIDC_EDITOR_GROUPS=alluredeck-editors
OIDC_STATE_COOKIE_SECRET=<32-byte-random-string>

Deployment Examples

Docker Compose

services:
  allure-api:
    environment:
      OIDC_ENABLED: "true"
      OIDC_ISSUER_URL: "https://login.microsoftonline.com/<tenant>/v2.0"
      OIDC_CLIENT_ID: "<client-id>"
      OIDC_CLIENT_SECRET: "<client-secret>"
      OIDC_REDIRECT_URL: "http://localhost:5050/api/v1/auth/oidc/callback"
      OIDC_ADMIN_GROUPS: "<admin-group-id>"
      OIDC_EDITOR_GROUPS: "<editor-group-id>"
      OIDC_STATE_COOKIE_SECRET: "<32-byte-random-string>"

Helm Chart

api:
  oidc:
    enabled: true
    issuerUrl: "https://login.microsoftonline.com/<tenant>/v2.0"
    clientId: "<client-id>"
    clientSecret: "<client-secret>"
    redirectUrl: "https://alluredeck.example.com/api/v1/auth/oidc/callback"
    adminGroups: "<admin-group-id>"
    editorGroups: "<editor-group-id>"
    stateCookieSecret: "<32-byte-random-string>"

Generating Secrets

The OIDC_STATE_COOKIE_SECRET must be exactly 32 bytes. Use any of these methods to generate one:

# OpenSSL
openssl rand -base64 32 | head -c 32

# Python
python3 -c "import secrets; print(secrets.token_urlsafe(24)[:32])"

# /dev/urandom
head -c 32 /dev/urandom | base64 | head -c 32

Troubleshooting