RBAC & roles

Every control-plane endpoint (/admin/v1/*) is protected by role-based access control. There are three roles, and a request's role is resolved on every call from the authenticated identity.

---

The three roles

| Role | What it can do | |---|---| | admin | Full configuration and write access — including destructive and high-privilege operations such as OpenAPI artifact generation, hard-delete of a service, and managing role/permission bindings. | | operator | Manage day-to-day configuration — services, operations, mappings, backend profiles, versions, and settings — without the admin-only destructive operations. | | reader | Read-only access to configuration and observability surfaces (dashboards, metrics, SLO reports, logs, audit history). No write access. |

Roles are hierarchical in spirit: anything a reader can see, an operator and admin can see too; write paths require operator or admin as documented per endpoint in the Admin API reference.

---

How a role is resolved

When a request arrives, the admin API determines the caller's identity and then maps that identity to a role. Resolution happens in a defined order so there is always a durable fallback and you are never locked out by a single failing dependency:

1. Direct in-app principal bindings (checked first). An operator can assign a specific user email directly to a role inside the product. These bindings are stored in the product's own database (table s2r_principal_role_binding) and do not depend on any external group lookup. This is the durable, always-available path — the recommended primary model for most installations.

2. Forwarded IdP group headers. When the identity-aware proxy forwards the caller's group membership (for example via X-Goog-Authenticated-User-Groups), the product maps those groups to roles using the configured group→role bindings (table s2r_role_binding).

3. Directory group lookup. On Google Cloud, if group headers are not forwarded, the admin API can resolve the caller's group membership through the Cloud Identity Groups API using the configured role-binding group emails. This path requires the directory API to be enabled and the service account to have appropriate directory read permission; group-based resolution is off by default and enabled explicitly per environment.

4. Emergency bootstrap env vars. For ingress paths that forward neither identity nor group headers, or for first-boot bring-up before any binding exists, the admin API can map specific actor emails to roles via bootstrap environment variables:

   • S2R_ADMIN_BOOTSTRAP_EMAILS → admin
   • S2R_ADMIN_BOOTSTRAP_OPERATOR_EMAILS → operator
   • S2R_ADMIN_BOOTSTRAP_READER_EMAILS → reader

   These are a deliberate break-glass mechanism. Keep the lists tight, and migrate to in-app principal bindings (path 1) or IdP groups (path 2) for steady-state operation.

---

Managing role assignments

Two sets of bindings are managed through the control plane:

• Group→role bindings map your identity provider's groups to product roles. Read with GET /admin/v1/role-bindings; replace with PUT /admin/v1/role-bindings.
• Direct user→role bindings map an individual user email to a role inside the app. List with GET /admin/v1/permission-bindings; create or reactivate with POST /admin/v1/permission-bindings; deactivate with DELETE /admin/v1/permission-bindings/{bindingId}.

The currently resolved identity and role for the caller are available at GET /admin/v1/me, which the UI uses to render the appropriate controls. Every binding change is recorded in the audit trail.

---

Who can manage RBAC

Managing role and permission bindings is an admin-level operation. Reader and operator accounts cannot grant or revoke roles.

---

Recommended model

For most installations:

• Let your identity-aware proxy control who can reach the product at all (the front door).
• Use direct in-app principal bindings to control which role each person gets inside the product (the durable path that survives directory hiccups).
• Reserve the bootstrap env vars strictly for break-glass and first-boot.

---

All Specaria SOAP to REST docs