# SSO Integration Project Memory

## Project Structure
- Planning workspace: `/home/josie/development/archlinux/sso/`
- Infrastructure repo: `/home/josie/development/archlinux/infrastructure/`
- Aurweb codebase: `/home/josie/development/archlinux/packaging/aurweb/`
- Archweb codebase: `/home/josie/development/archlinux/archweb/`
- Archwiki codebase: `/home/josie/development/archlinux/archwiki/`
- PoC config notes: `notes/aurweb-poc-keycloak.txt`, `notes/archweb-poc-keycloak.txt`, `notes/wiki-poc-keycloak.txt`
- Design docs: `docs/plans/` (wiki-sso-design, wiki-sso-plan, wiki-sso-infra-plan)

## Keycloak
- Instance: auth.josie.cloud (v26.5.3, operator-managed on OCP)
- Realm: josie
- Admin: temp-admin (see archweb notes for password)
- Test user: testdev / testpass (in Developers group, sub: a135bad2-5164-44bc-a5e9-c6ff4cc21af9)
- Admin API: `https://auth.josie.cloud/admin/realms/josie/...`
- Auth token: POST to `/realms/master/protocol/openid-connect/token`

## Archweb SSO (Phase 1 - PoC complete, infra branch ready)
- PoC client ID: archweb-poc
- Production client ID: openid_archweb
- Django OIDC integration using mozilla-django-oidc
- Routes: /oidc/callback/, /devel/link-sso/, /devel/link-sso/callback/
- Model: UserProfile.sso_accountid field
- Infra: commit 34a809e0 on master (Terraform + Ansible)

## Aurweb SSO (Phase 2 - implementation complete, uncommitted fixes pending)
- Branch: sso-integration (6 commits)
- Client ID: aurweb-poc
- FastAPI + authlib integration
- Key files: aurweb/oauth.py, aurweb/routers/sso.py, aurweb/routers/sso_link.py
- Uncommitted: parse_id_token->userinfo fix, unlink route, template tweaks

## Wiki SSO (Phase 3 - PoC complete, infra branch ready)
- PoC branch: sso-integration in archwiki repo (2 commits on upstream master)
- Infra branch: archwiki-sso in infrastructure repo (5 commits on master)
- PoC client ID: wiki-poc / Production client ID: openid_archwiki
- MediaWiki 1.45.1 + PluggableAuth 7.5.0 + OpenIDConnect 8.3.0
- Custom SSOLink extension: Special:LinkSSO + PluggableAuthUserAuthorization hook
- Writes into OpenIDConnect's openid_connect table (no separate table needed)
- Dev: podman containers (PHP-FPM + nginx + MariaDB) on port 8083
- Infra changes: Terraform OIDC client + group mapper, Ansible defaults/tasks/template
- Deployment prereqs: merge archwiki branch, add vault secret, update version, terraform apply, ansible deploy

## Key Lessons
- Always use `oauth.sso.userinfo(token=token)` not `parse_id_token` with Keycloak
- Keycloak redirect_uri matching is exact (trailing slash matters)
- aurweb schema bootstrap: `python -m aurweb.initdb` (not alembic)
- aurweb passwords: use `user.update_password()` not manual bcrypt
- Use python:3.13-slim for aurweb containers (3.14 breaks poetry)
- Set PYTHONDONTWRITEBYTECODE=1 in bind-mounted dev containers
- MW openid_connect table: oidc_subject/oidc_issuer are tinyblob not varchar
- OpenIDConnect stores issuer WITH trailing slash from providerURL config
- $wgPluggableAuth_EnableAutoCreation does NOT exist in PluggableAuth 7.5.0
- Use PluggableAuthUserAuthorization hook to prevent auto-creation
- MW special page title i18n key = lowercase page name (e.g. "linksso")
- MW installer requires 10+ char passwords
- After restarting podman PHP-FPM container, also restart nginx container
- MW OpenIDConnect discovers scopes via OIDC discovery, no MW config variable for it
- Ansible composer tasks need `creates:` guard for idempotency
- Client-level group mapper attaches claim directly, no separate optional_scopes needed