---
type: User Story
title: Authenticate administrators with Keycloak SSO
description: The operator console requires a Keycloak identity with the configured administrator role.
tags: [admin, keycloak, oidc, authentication]
timestamp: 2026-08-01T18:43:58Z
story_id: US-011
status: verified
---

# User Story

As an administrator, I want to authenticate through organizational SSO, so that privileged operations use centrally managed identities and roles.

# Acceptance Criteria

- [x] Admin authentication uses Keycloak OpenID Connect authorization code flow.
- [x] Sign-in is denied when the configured required role is absent.
- [x] Realm and configured-client roles are extracted from fresh Keycloak tokens.
- [x] Admin console layouts redirect unauthenticated or unauthorized users to the admin login page.
- [x] Every privileged server action independently rechecks the admin session and role.
- [x] Admin sessions use signed JWT behavior managed by NextAuth.
- [x] Administrators can sign out and return to the restricted login page.

# Implementation

- [`apps/web/src/lib/auth/admin-auth.ts`](../apps/web/src/lib/auth/admin-auth.ts)
- [`apps/web/src/lib/auth/require-admin.ts`](../apps/web/src/lib/auth/require-admin.ts)
- [`apps/web/src/app/admin`](../apps/web/src/app/admin)
- [`docs/admin-oidc-keycloak-setup.md`](../docs/admin-oidc-keycloak-setup.md)

# Validation

OIDC role extraction is covered by [`packages/auth/test/oidc-roles.test.ts`](../packages/auth/test/oidc-roles.test.ts).

# Related Stories

- [Operate settings and audit views](us-012-admin-operations.md)
- [Administer users](us-013-admin-user-management.md)