feat: allow granting Platform Admin by OIDC subject in gateway config #2613

Problem Statement

Today, granting Platform Admin privileges on an OpenShell gateway requires the IdP to assign a specific role (e.g. openshell-admin) in the JWT claims. There is no way to designate a specific OIDC subject (sub claim) as a Platform Admin directly in the gateway configuration. This creates friction when bootstrapping a new gateway (chicken-and-egg: you need an admin to configure roles, but the admin role must come from the IdP), when the IdP doesn't support custom roles, or when an operator wants gateway-local admin overrides independent of IdP role assignments.

A gateway-level admin_subjects configuration option would grant Platform Admin to specific OIDC subjects regardless of their JWT role claims, working alongside the existing role-based admin check — either mechanism grants admin access.

Technical Context

The gateway's authorization system has two layers that enforce admin status:

1. Middleware-level RBAC (AuthzPolicy.check()) — evaluates whether an authenticated identity's roles include the configured admin_role to gate access to platform-admin-scoped gRPC methods.
2. Handler-level workspace authorization (workspace_authz::is_platform_admin()) — called directly by gRPC handlers to bypass workspace membership checks for platform admins.

Both layers currently check only the identity's JWT roles against the configured admin_role string. The OIDC subject (sub claim) — already available on the Identity struct — is never consulted for admin status determination.

Affected Components

Technical Investigation

Architecture Overview

Authentication and authorization are separated per RFC 0001. Authentication providers (OIDC, mTLS, etc.) produce an Identity with subject, display_name, roles, and scopes. The authorization layer then evaluates this identity without knowing which provider authenticated the caller.

The admin check flows through two paths:

Path 1 — Middleware RBAC (authz.rs):
OidcConfig.admin_role → AuthzPolicy.admin_role (constructed in multiplex.rs:287) → AuthzPolicy.check() compares identity.roles against admin_role to gate platform-admin-scoped gRPC methods.

Path 2 — Handler workspace authorization (workspace_authz.rs):
OidcConfig.admin_role → ServerState.admin_role (set in lib.rs:208) → passed as &state.admin_role to authorize_workspace() / require_platform_admin() → calls is_platform_admin(identity_roles, admin_role) which checks admin_role.is_empty() || identity_roles.iter().any(|r| r == admin_role).

Both paths have access to Identity.subject but never check it for admin determination.

Code References

Current Behavior

The core admin determination happens in workspace_authz.rs:

fn is_platform_admin(identity_roles: &[String], admin_role: &str) -> bool {
    admin_role.is_empty() || identity_roles.iter().any(|r| r == admin_role)
}

When admin_role is empty (OIDC not configured or auth-only mode), every authenticated user is treated as platform admin. Otherwise, the user must have the admin_role in their JWT roles claim.

At the middleware level, AuthzPolicy.check() similarly compares identity.roles against admin_role to determine if the caller can access platform-admin-scoped methods. Admin role holders implicitly satisfy user-role requirements.

There are ~30+ call sites across grpc/sandbox.rs, grpc/workspace.rs, grpc/service.rs, grpc/provider.rs, grpc/policy.rs, and inference.rs that pass &state.admin_role to authorize_workspace(), authorize_sandbox_workspace(), or require_platform_admin().

What Would Need to Change

Config layer (openshell-core): Add admin_subjects: Vec<String> to OidcConfig. The deny_unknown_fields serde attribute means this must be an explicit field.

CLI layer (openshell-server/cli.rs): Add --oidc-admin-subjects CLI arg with OPENSHELL_OIDC_ADMIN_SUBJECTS env var. Add config-file overlay logic in the same pattern as admin_role.

Server state (openshell-server/lib.rs): Add admin_subjects field to ServerState, populated from config.oidc.admin_subjects in ServerState::new().

Middleware RBAC (authz.rs): Add admin_subjects: HashSet<String> to AuthzPolicy. Modify check() to also grant admin access when identity.subject is in admin_subjects.

Handler authorization (workspace_authz.rs): Modify is_platform_admin() signature to accept the caller's subject and the admin_subjects set. Update require_platform_admin(), authorize_workspace(), and is_platform_admin_principal() accordingly.

Call site churn mitigation: The ~30+ call sites that pass &state.admin_role would need updating. A recommended approach: introduce an AdminPolicy struct (or similar) that bundles admin_role and admin_subjects, then change ServerState to carry admin_policy: AdminPolicy and update the authorization function signatures to take &AdminPolicy. This localizes the change and prevents future churn if more admin criteria are added.

Multiplex (multiplex.rs): Update AuthzPolicy construction to include admin_subjects.

Helm chart: Add adminSubjects: [] to values.yaml under server.oidc. Render as admin_subjects = ["sub1", "sub2"] in the gateway-config.yaml template.

Docs: Update docs/reference/gateway-config.mdx and docs/reference/gateway-auth.mdx for the new config field, CLI flag, and env var.

Alternative Approaches Considered

1. Flat approach — add admin_subjects as a sibling field to admin_role in all signatures. Simpler to implement but results in ~30+ call-site changes and makes future admin-criteria additions equally expensive.

2. AdminPolicy struct — bundle admin_role + admin_subjects into one struct, thread that through instead of separate fields. More upfront work but reduces call-site churn to a type change and prevents future N+1 field threading. Recommended.

3. Synthetic role injection — when the subject matches admin_subjects, inject the admin_role into the identity's roles list at the authentication layer, before authorization runs. This would require zero changes to the authorization layer but mixes concerns: the auth layer would be modifying identity claims, which could confuse audit logging and GetCurrentUser responses. Not recommended.

Patterns to Follow

• Config fields: Follow the admin_role pattern — #[serde(default)] with a default function, matching CLI arg + env var + config-file overlay.
• CLI env vars: Use OPENSHELL_OIDC_ADMIN_SUBJECTS with comma-separated values (consistent with how list-type env vars are handled elsewhere).
• Helm values: Follow the existing OIDC block pattern with conditional rendering in the template.
• Tests: The workspace_authz.rs test module has thorough coverage of admin scenarios. New tests should follow platform_admin_bypasses_membership_check and auth_disabled_empty_admin_role_is_platform_admin patterns. authz.rs has role-based tests that should be extended for subject-based admin access.

Proposed Approach

Introduce an AdminPolicy struct that bundles the admin role name and admin subjects set, replacing the flat admin_role: String threading. Add admin_subjects to OidcConfig (config), CLI args (with env var OPENSHELL_OIDC_ADMIN_SUBJECTS), and the Helm chart. Modify is_platform_admin() and AuthzPolicy.check() to grant admin access when the caller's OIDC subject is in the configured admin_subjects set, alongside the existing role-based check. Update gateway config and auth documentation.

Scope Assessment

• Complexity: Medium — well-scoped changes across multiple files, but the pattern is clear and mechanical
• Confidence: High — clear path forward, no architectural unknowns
• Estimated files to change: ~15 (config, CLI, server state, 2 auth modules, multiplex, Helm values + template, 2 docs pages, plus test updates)
• Issue type: feat

Risks & Open Questions

• Revocation latency: Admin subjects are static in gateway config — revoking an admin subject requires a gateway restart (or config reload if supported). Should be documented as an operational consideration.
• Audit trail: When a user is granted admin via admin_subjects rather than IdP roles, the GetCurrentUser response won't show an admin role in roles[]. Operators may want to distinguish how admin access was granted. Consider whether the auth grant path should be surfaced (e.g. in logs or response metadata).
• Auth-only mode interaction: When both admin_role and user_role are empty (auth-only mode), everyone is already admin. admin_subjects should be a no-op in that mode — document this.
• CLI arg format: Comma-separated OPENSHELL_OIDC_ADMIN_SUBJECTS=sub1,sub2 or multi-value --oidc-admin-subject sub1 --oidc-admin-subject sub2? Clap supports both; comma-separated env var + multi-value CLI flag is the most ergonomic.
• Large subject lists: For gateways with many admin subjects, a HashSet<String> is appropriate for O(1) lookup. The current role check is O(n) on roles which is fine for small role lists.

Disposition Readiness

• State: validated
• Assessment: The investigation identified all affected code paths, confirmed feasibility, and mapped the implementation surface. The feature is a well-scoped addition to an existing, well-tested authorization system with clear patterns to follow.
• Missing evidence: None

Test Considerations

• Unit tests in workspace_authz.rs: Add tests for subject-based admin grant, subject-based admin with workspace membership bypass, subject-based admin + role-based admin coexistence, and empty admin_subjects (no effect).
• Unit tests in authz.rs: Add tests for admin_subjects granting access to platform-admin-scoped methods.
• Config serialization tests: Ensure admin_subjects round-trips through TOML serialization/deserialization.
• CLI integration tests: Verify OPENSHELL_OIDC_ADMIN_SUBJECTS env var and --oidc-admin-subjects CLI arg are parsed correctly.
• Helm template tests: Extend deploy/helm/openshell/tests/gateway_config_test.yaml to verify admin_subjects rendering.
• E2e tests (optional): The existing e2e/rust/tests/oidc_pkce.rs tests could be extended with a Keycloak user whose subject (not role) is configured as admin_subjects, but this is a stretch goal given the e2e test infrastructure required.
• Existing test patterns: Follow the platform_admin_bypasses_membership_check and auth_disabled_empty_admin_role_is_platform_admin patterns in workspace_authz.rs. The test module creates user_principal(subject, roles) helpers that can be reused.

Created by spike investigation. Validated means the issue is ready for human disposition. A human applies state:accepted if OpenShell should pursue the work and places it on the roadmap separately. To queue unattended agent planning, a human applies agent:plan-requested; a direct request to an agent does not require that label.