keycloak-sso-gateway

Ready-to-run OIDC / Keycloak callback server for a fleet of Telegram bots and domain web apps. One public HTTPS origin; configure targets via env and deploy with Docker Compose (or python -m keycloak_sso_gateway).

Companion bot adapter: aiogram-keycloak-sso (GitHub) — bots never expose HTTP; this gateway owns /sso/callback. Wire DTOs (SSOSession, login events, Redis prefixes) are duplicated in both packages and must stay in sync (schema_version).

Install

pip install "keycloak-sso-gateway[redis]"
# or without Redis extras if you only need the library pieces:
pip install keycloak-sso-gateway

Import package name (underscore): keycloak_sso_gateway.

CLI entry points:

keycloak-sso-gateway
# same as:
python -m keycloak_sso_gateway

Local run

cp .env.example .env   # fill SSO_* / GATEWAY_* / REDIS_URL
pip install -e ".[redis]"
python -m keycloak_sso_gateway

main() auto-loads .env from the current working directory (or the path in SSO_ENV_FILE). Existing process environment variables are never overwritten. Missing file → no-op.

Docker Compose

Host port 8091 → container 8080. Shared network name: sso-fleet.

cp .env.example .env   # fill SSO_* / GATEWAY_*
docker network create sso-fleet   # once
docker compose up -d --build
# local: http://localhost:8091/sso/callback

Compose still uses env_file: .env and overrides REDIS_URL / PORT for the container. PUBLIC_CALLBACK_URL must be the public HTTPS URL registered in Keycloak (edge TLS in front of :8091), not the container-local address.

Public URLs

Bots never call /sso/login; they build the authorize URL themselves (via aiogram-keycloak-sso) and only need this gateway as the shared callback + Redis session/event bus.

Modes

Bot (shared Redis)

1. Bot builds authorize URL with state=bot:<bot_id>:<hmac> (legacy <bot_id>:<hmac> still accepted).
2. Keycloak redirects to /sso/callback.
3. Gateway exchanges the code, writes the session to Redis, publishes a login event, redirects to t.me/... or shows success HTML.

Web (one-shot handoff)

1. Browser (or web backend redirect) hits
   GET /sso/login?app_id=portal&return_uri=https://app.example.com/sso/complete&next=/dashboard
   (return_uri must be allowlisted in GATEWAY_WEB_APPS).
2. Gateway 302 → Keycloak; Keycloak returns to the same /sso/callback.
3. Gateway stores tokens under a handoff id (TTL ~120s) and 302 to return_uri?handoff=....
4. Web backend POST /sso/handoff once, gets tokens + claims, sets its own cookie/session.

Web apps do not poll Redis bot sessions.

Environment

GATEWAY_WEB_APPS

app_id=https://app.example.com/sso/complete;crm=https://crm.example.com/done,https://crm.example.com/dev

• ; separates apps
• , separates allowlisted return_uri values for one app
• empty / unset → bots only

Wire contract

Redis key prefixes and JSON shapes (SSOSession, login events, handoff payload, schema_version) are the shared bus contract with bot processes (aiogram-keycloak-sso). Keep them in sync with consumers.

Development

pip install -e ".[dev,redis]"
pytest

Optional smoke helpers live under integration/ when present.