RBAC, Teams & Organizations

Safeguard's identity and access layer is built for organizations that need clear ownership boundaries, tight least-privilege defaults, and a full audit trail.

Hierarchy

Organization
  └─ Team
     └─ Project
        └─ Asset

• Organization — the top-level tenant boundary. Billing, SSO, audit log, compliance configuration live here.
• Team — a group of users with shared access. Roles are scoped to a team or to the whole organization.
• Project — a unit of ownership inside a team (often one project per service or repository).
• Asset — concrete things (repositories, images, SBOMs, vendors, workloads) assigned to a project.

A user can belong to multiple teams and hold different roles in each.

Roles

Built-in roles:

Custom roles are composed from a permissions matrix:

apiVersion: safeguard.sh/v1
kind: Role
metadata:
  name: production-responder
spec:
  permissions:
    - findings:read
    - findings:triage
    - policies:evaluate
    - workflows:run
  restrictions:
    environments: ["production"]
    severity_max: "critical"

SSO

Safeguard supports:

• SAML 2.0 — all major IdPs (Okta, Entra ID, Google Workspace, OneLogin, Duo, JumpCloud, PingID, Authentik, Keycloak).
• OpenID Connect — any OIDC 1.0 provider.
• SCIM 2.0 — automated user provisioning and deprovisioning.
• Just-in-time provisioning — users are created on first SSO login with a default role you configure.

Enterprise tenants can require SSO for every login (no local passwords) and require re-authentication for sensitive actions (policy changes, approving exceptions).

See SSO Authentication Setup for step-by-step configuration instructions per provider, including Google Workspace, Microsoft Entra ID, Okta, and OneLogin.

MFA

• WebAuthn / passkeys (preferred).
• TOTP via authenticator apps.
• Hardware security keys (FIDO2).
• Phone/SMS MFA is disabled by default and not available in FedRAMP tenancies.

Policies can require a specific MFA level for specific actions (e.g., "promoting a self-heal to production requires a passkey re-auth").

API Keys and Tokens

Safeguard has two distinct families of long-lived credential: user API keys (and the related service tokens / workload identities), which all act as something scoped under a user or service identity, and organization secret keys, which act as the organization itself. They're easy to confuse because both let something authenticate against Safeguard programmatically, but they're generated in different places, used for different purposes, and revoked with different effects — see User API keys vs. organization secret keys below before deciding which one you need.

User API keys

• User API keys — bound to a user, inherit the user's role. Revoked if the user is deprovisioned.
• Service tokens — bound to a service identity, used for CI / automation. Scoped to specific permissions.
• Workload identities — OIDC-federated tokens from GitHub, GitLab, AWS, Azure, GCP. No long-lived secrets.

All tokens are short-lived by default (max 1 hour unless explicitly extended), and their usage is auditable.

Generate at Settings → API Keys or with:

safeguard tokens create --name ci-autofix --scope "workflows:run policies:read" --ttl 90d

Organization secret keys

A secret key is scoped to your organization, not to any individual user — it's the credential the Guard SDK uses to pull your organization's live policy into an embedded agent or MCP server process. Because it belongs to the organization rather than a person, a secret key keeps working across individual user offboarding: revoking a user's account (see Deprovisioning below) has no effect on any secret key, since the key was never tied to that user in the first place.

Secret keys are generated from Settings → Developer. The generation flow (naming a purpose, copying the one-time key value, and wiring it into your agent process via the SG_SECRET_KEY environment variable) is already covered step-by-step in Guard SDK: Generate a Secret Key — follow that page rather than re-deriving the steps here.

The Developer tab is currently only visible under the ESSCM product context. If you don't see it under Settings, check that you're viewing Settings from within ESSCM.

Managing and revoking secret keys

Existing keys are listed on the Developer tab, where each key can be revoked or deleted individually.

Revoking a secret key takes effect immediately. Any Guard SDK instance still configured with that key will fail to pull fresh policy on its next background sync — treat revocation as an immediate, org-wide cutoff, not a graceful rollover.

User API keys vs. organization secret keys

Common errors: a Guard SDK instance suddenly failing to refresh its policy is expected behavior if its secret key was recently revoked or deleted from the Developer tab — generate a new key and reconfigure the affected instance rather than treating it as an outage. For SDK-side connection and startup issues unrelated to key revocation, see the Guard SDK FAQ & Troubleshooting.

Audit Log

Every action that mutates state is recorded:

• Who (user, service, workload identity).
• What (action + before/after where applicable).
• When (UTC + timezone).
• Where (IP, session ID, client type).
• Why (linked ticket / PR / policy exception if provided).

Audit log is append-only, cryptographically chained, and retained for the period your tenancy allows (90 days default; up to 7 years configurable for Enterprise).

A single entry follows the same who/what/when/where/why shape described above; illustratively:

{
  "id": "audit_01J9K...XYZ",
  "actor": { "type": "user", "id": "usr_4f2a", "email": "jane@acme.com" },
  "action": "role.assigned",
  "before": { "role": "Viewer" },
  "after": { "role": "Security Engineer" },
  "target": { "type": "team", "id": "team_payments" },
  "occurred_at": "2026-06-14T18:22:41.003Z",
  "ip": "203.0.113.42",
  "session_id": "sess_9c1d",
  "client": "web",
  "reason": { "type": "exception_link", "ref": "exc_7781" }
}

Field names above illustrate the who/what/when/where/why shape, not a literal fixed export schema — treat this as the concept, not an exact field reference.

This is the RBAC/organization audit log — the record of who changed what in Safeguard itself (role grants, key revocations, settings changes). It's distinct from Guard's own request-level audit trail, which records every allow / deny / monitor decision Guard makes on agent traffic. See Audit Trail & Alerts if you're looking for that instead.

Audit streaming

Stream the audit log to your SIEM in real time via:

• Webhook (JSON per event).
• S3 with scheduled batch export.
• OpenTelemetry logs.
• Splunk HEC.

To stream via webhook, subscribe to the audit.action event — the same event catalog and delivery mechanism (signed payloads, retries, DLQ) described in Webhooks & Events applies here:

safeguard webhooks create \
  --url https://siem.example.com/ingest/safeguard \
  --events audit.action \
  --secret $(openssl rand -hex 32)

Approval Workflows

Sensitive actions can require multi-party approval:

• Policy changes.
• Large exception grants.
• Production-impacting auto-fix merges.
• Service-token creation.
• Org-level configuration changes.

Configure under Settings → Approvals.

This is the RBAC side of who is allowed to approve. The approver list for a specific guardrail exception is configured at the policy level, as part of the rule itself — for example, the exception.approvers field on a blocking rule:

rules:
  - id: no-known-exploited-critical
    effect: BLOCK
    exception:
      allowed: true
      approvers: ["security-leads@company.com"]

See Guardrails & Enforcement: Exceptions and Breakglass for the full policy-level mechanics — this page covers the org's role and approval model that governs who can act in that capacity.

Break-Glass

Emergency access for incident response:

• A break-glass role grants elevated permissions for a time-boxed window.
• Break-glass invocations require two approvers and notify the entire security team.
• Every break-glass action is separately labeled in the audit log and reviewed post-incident.

This is the same "emergency breakglass exception" mechanism described from the guardrail-enforcement side in Guardrails & Enforcement: a two-person approval requirement backed by a role grant, applied to a specific blocking guardrail rather than to the whole organization.

Per-Asset Permissions

Permissions can be sliced by asset labels:

- role: Security Engineer
  scope:
    labels:
      team: payments
      env: [production, staging]

Useful for consultants and contractors who should only see a specific service.

Deprovisioning

When a user is deprovisioned (SCIM or manual):

• All sessions revoked.
• All user API keys revoked.
• All pending approvals reassigned to their team.
• Actions they took remain in the audit log forever.

Service tokens, workload identities, and organization secret keys are not touched by deprovisioning — they're bound to a service identity or the organization, not to the departing user's account (see User API keys vs. organization secret keys above). If the person leaving was the one who created a CI service token or a Guard SDK secret key, revoke those separately as part of offboarding.

FAQ & Troubleshooting

I see different role names (Admin, Manager, Contributor, Viewer) somewhere else in Safeguard — is that the same RBAC system as this page? No. This page documents the core organization/team RBAC model (Owner, Admin, Security Lead, Security Engineer, Developer, Auditor, Viewer). Some product surfaces layer their own role vocabulary on top for that surface only — for example see Portal User Roles for Portal's Admin / Manager / Contributor / Viewer roles. If a permission looks wrong, check which role system the page you're on is actually describing before assuming it's a bug.

I deprovisioned a user, but a service they set up (a CI job, an MCP server using the Guard SDK) is still authenticating successfully. Is that a bug? No — that's expected. Deprovisioning only revokes credentials tied to the user's own account (sessions, user API keys). Service tokens, workload identities, and organization secret keys are independent of any one user by design, so they keep working after that person leaves. Revoke them explicitly if they should no longer be trusted.

We deprovisioned a user via SCIM but their access didn't disappear instantly — why? SCIM deprovisioning is triggered by your IdP pushing a deactivation event to Safeguard, not by Safeguard polling the IdP. If your IdP batches or schedules SCIM syncs (common with some group-based deprovisioning setups) rather than pushing immediately on offboarding, there can be a delay before Safeguard receives the event. For anything time-sensitive, deprovision manually from Safeguard as well rather than relying solely on SCIM timing.

What's the difference between the "Audit Log" on this page and Guard's "Audit Trail"? This page's audit log records changes to Safeguard itself — role grants, key revocation, settings changes, approvals. Guard's audit trail is a separate, higher-volume log of every individual allow / deny / monitor decision Guard makes on agent/MCP traffic. Both are audited and both are exportable, but they answer different questions: "who changed what in Safeguard" versus "what did Guard do with this request."

A custom role isn't granting the access I expect — where do I start debugging? Check the permissions list and any restrictions block on the role definition first (for example, a severity_max or environments restriction silently narrows an otherwise-broad permission, as in the production-responder example above). Then check whether the user's access is coming from the role you think it is — a user in multiple teams can hold a different role in each, so confirm which team scope the resource you're testing falls under.

Related

• Web Application — SSO login flow.
• Desktop Application — per-user system-access consent.
• Organization Management — org-level configuration surface.
• Guard SDK — generate and use an organization secret key to embed live policy enforcement in an agent or MCP server.
• SSO Authentication Setup — provider-by-provider SAML/OIDC/OAuth configuration.
• Guardrails & Enforcement — where exception approvers and breakglass are configured at the policy level.
• Webhooks & Events — the full event catalog and delivery mechanics behind audit streaming.
• Audit Trail & Alerts — Guard's own per-request audit trail, distinct from the organization audit log on this page.
• Portal User Roles — Portal's separate, surface-specific role system.
• Compliance — how RBAC maps to compliance controls.