HEXALGON SSO

HEXALGON SSO is the browser-facing OIDC broker in the Hexalgon auth stack. It owns authentication, brokered SSO sessions, MFA, consent, upstream federation, and downstream token issuance. Tenant-local authorization still belongs in HEX IAM.

Current capabilities

• OIDC authorization code flow with PKCE
• Local username/password login
• TOTP MFA for local accounts
• Persistent user consent with grant and deny flows
• Refresh tokens with rotation and replay rejection
• Audit logging with searchable endpoints
• Upstream OIDC federation for social and enterprise login
• Database-backed asymmetric signing keys with multi-key JWKS output
• Admin-authenticated upstream provider management
• SQLite for development and PostgreSQL for production
• SQL migrations via yoyo-migrations

Core HTTP surface

Public OIDC and browser endpoints:

• GET /.well-known/openid-configuration
• GET /oidc/jwks
• GET /oidc/authorize
• POST /oidc/login
• POST /oidc/mfa/totp
• POST /oidc/consent/grant
• POST /oidc/consent/deny
• POST /oidc/token
• POST /oidc/logout
• GET /oidc/userinfo
• GET /oidc/upstream/start
• GET /oidc/upstream/callback/{provider_id}

Admin endpoints:

• POST /admin/login
• POST /admin/logout
• GET /admin/providers
• POST /admin/providers
• PUT /admin/providers/{provider_id}
• DELETE /admin/providers/{provider_id}
• GET /oidc/audit/logs
• GET /oidc/audit/logs/count

Development bootstrap endpoints, gated by ENABLE_DEV_ENDPOINTS=true:

• POST /dev/users
• POST /dev/clients
• POST /dev/providers
• POST /dev/mfa/totp/enroll

Auth flow behavior

Local browser flow:

1. Client starts at /oidc/authorize
2. User signs in at /oidc/login
3. If MFA is enabled, broker pauses at /oidc/mfa/totp
4. If consent is missing or scope set changed, broker pauses at consent
5. Broker returns an authorization code
6. Client exchanges code at /oidc/token

Refresh flow:

1. Client sends grant_type=refresh_token
2. Existing refresh token is validated
3. Old token is revoked
4. New access token, ID token, and refresh token are issued

Signing keys and JWKS

Token signing stays behind the existing TokenSignerPort, but the concrete adapter is now asymmetric and database-backed.

• Default algorithm: RS256
• Supported algorithms in the signer: RS256, ES256
• Primary signing key is stored in signing_keys
• Old active keys remain available in JWKS until expiry
• JWKS now returns multiple keys
• Legacy PEM files are imported once if present, then signing moves to the database-backed key store

Relevant settings:

• SIGNING_KEY_ALGORITHM=RS256
• SIGNING_KEY_ROTATION_DAYS=90

Admin bootstrap

The broker can seed one admin user on startup:

• ADMIN_BOOTSTRAP_USERNAME
• ADMIN_BOOTSTRAP_PASSWORD
• ADMIN_BOOTSTRAP_PERMISSIONS=manage_providers,view_audit_logs

If bootstrap credentials are empty, no admin is seeded.

Runtime configuration

Important environment variables:

APP_BASE_URL=http://localhost:8000
ISSUER=http://localhost:8000
DATABASE_BACKEND=sqlite
POSTGRES_DSN=postgresql://postgres:postgres@localhost:5432/hexalgon_sso
DATA_DIR=.data

ACCESS_TOKEN_TTL_SECONDS=3600
ID_TOKEN_TTL_SECONDS=3600
REFRESH_TOKEN_TTL_SECONDS=2592000
SIGNING_KEY_ALGORITHM=RS256
SIGNING_KEY_ROTATION_DAYS=90

SESSION_COOKIE_NAME=hex_sso_session
ADMIN_SESSION_COOKIE_NAME=hex_sso_admin_session
ENABLE_DEV_ENDPOINTS=false
ENABLE_LOCAL_LOGIN=true

Secrets encrypted at rest:

• downstream OIDC client secrets
• upstream provider client secrets
• user TOTP secrets
• private signing keys stored in the database

Encryption uses Fernet with either:

• ENCRYPTION_KEY, or
• DATA_DIR/enc.key

Running locally

Install dependencies and apply migrations:

poetry install
poetry run python -m app.database.run_migrations apply
poetry run uvicorn app.main:app --reload

Useful test command:

poetry run pytest -q

The test harness now clears persistent SQLite test data between runs, so repeated local test execution should stay stable.