Pulse/docs/OIDC_SCOPE_GROUP_AUTH_FIX_SPEC.md

# OIDC Scope And Group Authorization Fix Spec

## Status

Resolved on 2026-07-07; see Resolution. Reporter retest still requires a
release artifact containing both fixes.

Primary issue: #1535

Related issues: #1528, #1533

Governed owners:

- `api-contracts`: SSO provider API payloads, OIDC login initialization, callback authorization, session identity.
- `frontend-primitives`: Settings -> Security -> Single Sign-On provider configuration.

This document is a handoff spec. It is not a solution design.

## User-Visible Failure

Settings-configured OIDC can complete part of the login flow, but group-based authorization and role mapping still fail for reporters using v6.0.4 through v6.0.5-rc.3.

The visible failure reported on #1535 after v6.0.5-rc.3:

- the displayed username/session label is no longer the internal `sso:oidc:...` principal
- group authorization still fails with `Your account is not part of an authorized group to use Pulse.`
- the observed OIDC authorization request scope is only `openid profile email`
- the reporter expects a configured group claim to be available for group role mapping

Reported IdPs:

- Pocket ID
- Authentik

## What Is Already Fixed

The following commits are present on `origin/main` and in the v6.0.5 RC line:

- `caa9b41834` `Fix OIDC provider detail persistence`
  - Fixes SSO provider API/detail persistence for nested OIDC fields, groups claim, allowed groups, and group role mappings when the payload supplies them.
  - References #1521.
- `1c8a9346ef` `Fix legacy OIDC SSO discovery and CSP nonce`
  - Restores the saved/legacy OIDC discovery path and SSO button behavior.
  - References #1533.
- `eb99d7a6b3` `Fix SSO session display labels`
  - Keeps the provider-scoped SSO principal as the stable session owner while displaying the IdP username/email/display claim in app chrome.
  - References #1535.

These commits do not finish group-scope authorization for Settings-configured OIDC.

## Current Evidence

Current `origin/main` evidence:

- `internal/api/identity_sso_handlers.go`
  - OIDC provider detail responses expose nested OIDC scopes.
  - Create/update handlers can persist supplied OIDC scopes, groups claim, allowed groups, and group role mappings.
- `internal/api/sso_handlers_crud_test.go`
  - API tests prove a payload containing `["openid", "profile", "email", "groups"]` can round-trip through provider detail and persistence.
- `frontend-modern/src/components/Settings/ssoProvidersModel.ts`
  - The form model has `oidcScopes`.
  - The empty form default is `openid profile email`.
  - The payload builder sends `oidc.scopes` from `form.oidcScopes`.
- `frontend-modern/src/components/Settings/SSOProvidersPanel.tsx`
  - The OIDC create/edit UI exposes issuer, client, secret, redirect/logout, groups claim, allowed groups, allowed domains, allowed emails, and group role mappings.
  - The OIDC create/edit UI does not render an editable OIDC scopes field.
- `internal/api/oidc_handlers.go`
  - Login initialization falls back to `openid profile email` when provider scopes are empty.
  - Group restriction and group role mapping depend on the configured groups claim being present in the OIDC claims.
  - Group claim extraction already accepts arrays and comma/space-separated strings.

Commit history evidence:

- No commits from `v6.0.0..origin/main` touch `frontend-modern/src/components/Settings/SSOProvidersPanel.tsx`.
- No commits from `v6.0.0..origin/main` touch `frontend-modern/src/components/Settings/ssoProvidersModel.ts`.

## Expected Product Behavior

An administrator configuring OIDC through Settings must be able to view and edit the exact OIDC scopes Pulse uses for the authorization request.

The configured scopes must be the same scopes that:

- are saved by provider create/update
- are returned by provider detail
- are shown again when the provider is reopened for editing
- are used when Pulse builds the OIDC authorization request

For providers with no custom scopes configured, existing behavior remains:

- default scopes are `openid profile email`
- existing providers continue to work without requiring manual reconfiguration

For providers that require an extra group scope before returning group claims:

- a Settings-configured provider can request that scope
- Pulse can receive the configured group claim
- allowed-group checks use that claim
- group role mappings use that claim
- a matching group grants the mapped Pulse role
- a non-matching or missing group still fails closed

The v6 SSO identity invariant remains:

- the provider-scoped subject is the stable SSO principal
- `preferred_username`, email, or display name must not become the canonical session owner
- local-user linking by `preferred_username` must not be reintroduced as the authorization model
- app chrome should continue to display the IdP user-facing claim instead of the internal provider-scoped principal

## Non-Goals

This fix does not need to redesign SSO.

This fix does not need to change:

- SAML behavior
- proxy auth
- local username/password auth
- paid-tier gating
- the provider-scoped SSO principal model
- the visible v6 Settings navigation model

The callback/auth-routing failure reported in #1533 is related OIDC fallout, but it is distinct from the missing group-scope path unless evidence proves a shared root cause.

## Not Fixed If

The issue is not fixed if any of the following remain true:

- the API accepts custom OIDC scopes, but the Settings UI cannot configure them
- the Settings UI has a groups claim field, but the authorization request still omits the configured group scope
- Pulse globally adds `groups` to every OIDC provider without preserving admin-configured scope intent
- role mapping works only when the IdP happens to return groups under the default `openid profile email` request
- role mapping depends on matching a local Pulse user by `preferred_username`
- the display label regresses to `sso:oidc:...`
- existing providers with no custom scopes break
- reporter retest is requested before a release artifact actually contains the fix

## Required Proof

A complete fix needs proof for these outcomes:

- A Settings-created OIDC provider can save a non-default scope set such as `openid profile email groups`.
- Reopening that provider in Settings shows the same scope set.
- The authorization request generated for that provider includes the saved scope set.
- An OIDC callback containing the configured groups claim grants the mapped role.
- An OIDC callback without a matching group still fails closed.
- Existing providers with empty or missing scopes still use `openid profile email`.
- The #1535 display-label fix remains intact.
- The #1533 SSO button/discovery fix remains intact.
- Tests cover both backend payload persistence and the Settings UI path that a normal administrator uses.
- Browser proof exercises the Settings -> Security -> Single Sign-On create/edit path, not only source-level payload builders.

## Resolution (2026-07-07)

Two defects, two repos:

- repos/pulse `87aac4e57` adds the editable Scopes field to the Settings
  OIDC create/edit modal (the form model already round-tripped
  `oidc.scopes`; the panel never rendered an input for it), plus model and
  panel tests covering the create/edit round-trip.
- pulse-enterprise `689100c` fixes the deeper root cause. SSO admin
  endpoints are overridden by the enterprise binder
  (`pulse-enterprise/internal/ssoadmin/hooks.go`), and its provider detail
  GET used a local flat serialization that drops nested OIDC scopes, the
  groups claim, and group role mappings. Because SSO is license gated,
  every real install reads provider detail through that override, so
  reopening a provider showed defaults and the next save reset the saved
  scopes. The OSS-side persistence/detail fixes in `caa9b41834` never
  executed on licensed builds. Detail reads now delegate to the core
  handler, which returns the canonical nested payload.

Verified live against a dev enterprise build: a provider created with
`openid profile email groups` shows the same set when reopened, and the
`/api/oidc/{id}/login` redirect carries
`scope=openid+profile+email+groups`. Persistence and the authorization
request were already correct end to end; only the detail read path was
lossy.