---
title: Arch Linux SSO Migration Plan
date: 2026-02-20
tags:
  - archlinux
  - sso
  - keycloak
  - migration
  - proposal
status: draft
---

# Arch Linux SSO Migration Plan

> [!abstract] Purpose
> Proposal to integrate aurweb, archweb, and the Arch Wiki with the existing Keycloak SSO at accounts.archlinux.org. This is a draft for community review and comment.

## Background

Arch Linux runs a Keycloak instance at accounts.archlinux.org that provides SSO for GitLab, Matrix, HedgeDoc, Grafana, the Security Tracker, and buildbtw. Three major services remain outside SSO:

| Service | Framework | Users | Risk Level |
|---------|-----------|-------|------------|
| archweb | Django | ~hundreds (staff only) | Low |
| aurweb | FastAPI | ~tens of thousands | Medium |
| Arch Wiki | MediaWiki | Very large | High |

## Proposed Rollout Order

### Phase 1: archweb

**Why first**: Smallest userbase (staff only), most existing code (the `oidc` branch), clearest role mapping, lowest risk.

**Existing work**:
- [Issue #284](https://github.com/archlinux/archweb/issues/284) open since 2020
- `oidc` branch with 4 commits implementing `DevelOIDCAuthenticationBackend`, role mapping, and user sync
- Uses `mozilla-django-oidc`

**Tasks**:
1. Rebase `oidc` branch onto current master (194 commits behind)
2. Register `archweb` OIDC client in `tf-stage2/keycloak.tf`
3. Review and update role mapping against current Keycloak groups
4. Test on staging
5. Deploy with dual auth (local + SSO)
6. Link existing staff accounts by email, store OIDC `sub`
7. After verification period, disable local login

**User migration**: One-time email-based matching for existing devs/TUs, then all future auth via Keycloak. Small enough to handle manually if needed.

### Phase 2: aurweb

**Why second**: Larger userbase but auth is web-only (SSH keys for git are separate). Has DB preparation (SSO account ID column) already merged.

**Existing work**:
- [Issue #54](https://gitlab.archlinux.org/archlinux/aurweb/-/issues/54) open
- SSO account ID column in Users table (MR !67)
- SSO setup documentation (`doc/sso.txt`)
- authlib already in dependencies

**Tasks**:
1. Implement OIDC login flow using authlib (redirect to Keycloak, handle callback)
2. Register `aurweb` OIDC client in `tf-stage2/keycloak.tf`
3. Link OIDC `sub` claim to existing `SSOAccountID` column
4. Map Keycloak groups to AUR account types
5. Build account linking UI for existing users
6. Deploy with dual auth (password + SSO)
7. Gradual migration: new accounts via SSO only, existing users prompted to link
8. After migration period, disable local password login for web UI

**Key considerations**:
- SSH key auth for `git push` to AUR must remain functional throughout
- RPC API access (used by AUR helpers) should be unaffected
- Large userbase means self-service account linking is essential (can't do manual matching)

### Phase 3: Arch Wiki

**Why last**: Largest userbase, highest visibility, most complex migration. Benefits from lessons learned in phases 1 and 2.

**Existing work**:
- [infrastructure#38](https://gitlab.archlinux.org/archlinux/infrastructure/-/issues/38) open
- MediaWiki Extension:OpenID_Connect is mature and has Keycloak support

**Tasks**:
1. Install PluggableAuth + OpenIDConnect extensions (Composer, via Ansible)
2. Register `wiki` OIDC client in `tf-stage2/keycloak.tf`
3. Configure OIDC provider in `LocalSettings.php`
4. Implement `PluggableAuthPopulateGroups` hook for group mapping
5. Set up staging wiki for testing
6. Deploy with dual auth (`$wgPluggableAuth_EnableLocalLogin = true`)
7. Provide account linking flow for existing users
8. Handle bot accounts (keep MediaWiki bot passwords functional)
9. After migration period, disable local login
10. Disable local password changes (Keycloak owns credentials)

**Key considerations**:
- Username mismatch between MediaWiki and Keycloak accounts
- Bot and service accounts need continued bot password access
- Must not create duplicate accounts during migration
- Wiki admin team needs to be involved early for account support transition

## Cross-Cutting Concerns

### User Migration Strategy

Each phase faces the same core problem: linking existing service accounts to Keycloak identities.

**Recommended approach**:
1. **Initial matching by email** -- match service account email to Keycloak account email
2. **Store OIDC `sub` claim** -- after first SSO login, store the immutable `sub` identifier for future matching (emails can change)
3. **Self-service linking** -- provide a UI where users log in with their old credentials, then authenticate via Keycloak to link accounts
4. **Grace period** -- keep dual auth (local + SSO) active for a defined period per service
5. **Communication** -- announce timelines on arch-dev-public, wiki, and relevant channels

### Account Support

foxboron raised a valid concern: SSO centralizes account management, shifting support from service-specific admins to DevOps.

**Mitigation**:
- Document account recovery and support procedures for Keycloak
- Ensure Keycloak's self-service (password reset, 2FA management) is robust before migration
- Keep service-specific admin capabilities (e.g., wiki sysops can still manage wiki permissions, even if the account itself is in Keycloak)

### Keycloak Infrastructure Changes

Each phase requires adding a new OIDC client in `tf-stage2/keycloak.tf`:

```hcl
resource "keycloak_openid_client" "archweb" {
  realm_id    = keycloak_realm.archlinux.id
  client_id   = "openid_archweb"
  name        = "Archweb"
  access_type = "CONFIDENTIAL"
  valid_redirect_uris = ["https://archlinux.org/oidc/callback/"]
  # ...
}
```

Group/role claim mappers may need updating per service.

## Open Questions

1. **Scope of phase 1**: Should we just rebase the existing archweb `oidc` branch, or rewrite from scratch given it's 4+ years old?
2. **aurweb SSH keys**: Should SSH keys eventually move to Keycloak attributes, or remain in aurweb's DB?
3. **Wiki bot accounts**: What's the full inventory of bots and automated accounts that need continued local access?
4. **Timeline**: What's the appetite for doing this incrementally vs. a coordinated rollout?
5. **Keycloak open registration**: Currently disabled. Does the wiki require public registration? If so, Keycloak registration needs to be re-enabled (with hCaptcha).

## References

- [[Keycloak Infrastructure]] -- current Keycloak setup
- [[archweb SSO]] -- archweb research and existing code
- [[aurweb SSO]] -- aurweb research and existing work
- [[Wiki SSO]] -- wiki research and extension options
- [DeveloperWiki:Staff_Services](https://manual.archlinux.page/staff/staff-services/) -- which services use SSO today