Architecture · Permissions
Permissions & scopes
Shield's OAuth 2.1 enforcement model: how scopes are defined, evaluated and audited across every tool call and resource fetch.
OAuth 2.1 + OIDC
Shield implements the OAuth 2.1 profile (draft-ietf-oauth-v2-1) with mandatory PKCE for all flows. OIDC provides the identity layer: the ID Token carries the tenant_id, RBAC roles, and jurisdiction claims required by Shield's policy engine.
Unsupported flows (by design, not configuration):
- Implicit flow (RFC 6749 §4.2) — removed in OAuth 2.1
- Resource Owner Password Credentials — too broad, no per-request scope binding
- Client Credentials without mTLS — insufficient for multi-tenant isolation
The authorization code flow with PKCE is the only supported path for operator authentication. Machine-to-machine communication uses client_credentials with mTLS client certificates, never shared secrets.
Scoped tokens
All scopes follow the pattern resource:action[:qualifier]. A token without the required scope receives a 403 at the Shield perimeter edge — the request never reaches the target component.
| Scope | Component | Permitted action |
|---|---|---|
| vault:read | Vault | Read assets and resource handles |
| vault:write:tenant | Vault | Create or update tenant-scoped assets |
| audit:export | Chain | Export signed trace logs |
| audit:read | Chain | Read trace events (no export) |
| skill:execute:approved | Nexus | Execute skills in the approved catalog |
| skill:manage | Nexus | Add, version or deprecate skills |
| hub:read | Hub | Read connector registry |
| hub:write | Hub | Register or update connectors |
| admin:tenant:create | Shield | Provision a new tenant |
| admin:tenant:suspend | Shield | Suspend a tenant (requires 2-party approval) |
vault:write:tenant does not imply vault:read. Each scope must be explicitly present in the token.Least privilege by default
The four built-in RBAC roles ship with minimal scope sets. Operators may not grant scopes outside a role's permitted set without an architectural exception logged in Chain.
| Role | Scope set | Can do | Cannot do |
|---|---|---|---|
| admin | All scopes | Full system management | Nothing |
| director | audit:export, skill:manage, hub:read | Export logs, manage skills, read connectors | Create/suspend tenants, vault:write |
| operator | vault:read, audit:read, skill:execute:approved, hub:read | Day-to-day reasoning, read logs | Manage skills, export logs, admin actions |
| viewer | audit:read | Read-only trace inspection | Any write or execute |
Privilege escalation requires: a director-or-above initiating the change, a Chain trace recording the intent, and a second director countersigning within 24 hours. No single-party escalation is possible for admin-level scopes.
admin role exists for initial provisioning only. Cognitive Server recommends deactivating admin tokens immediately after tenant setup and operating exclusively under director/operator/viewer roles.