RBAC & SSO

This guide covers user roles, permissions, team management, and single sign-on (SSO) configuration. The model is built around 5 seeded roles with 27 permissions in feature:action format, three-layer tenant isolation, and SAML 2.0 / Google OAuth SSO with optional group-to-role mapping. Everything below applies tenant by tenant — your roles, your permissions, your audit log.

Why RBAC matters: every customer environment combines auditors who need read-only access, analysts who triage findings, and admins who change settings. Mixing those audiences on a single role creates either too-loose access (auditors see sensitive data) or too-tight access (analysts cannot acknowledge findings). The role catalog is designed to fit those audiences without customization for 95% of teams.

Role model

The platform ships with 5 hierarchical roles. Higher-level roles inherit the read permissions of lower-level roles. You assign one role per user per tenant — a user can hold different roles in different tenants if your org has several.

platform_admin is reserved for Onam SREs. It exists for support workflows that require an explicit, audit-logged impersonation handshake you approve.

The hierarchy is additive on reads and intersection-based on writes: a tenant_admin can do everything an analyst can, and an analyst everything a viewer can — but writes don't cascade upward, so a tenant_admin cannot perform org_admin actions like billing.

Permission matrix

All permissions follow the feature:action format: 27 permissions across 18 features and 4 action verbs (read, write, create, delete).

The permissions fall into four groups:

1. Base read (every role, including viewer) — 9 read permissions on non-sensitive engines: discoveries, inventory, check, threat, compliance, iam, network, risk, plus scans:read and reports:read.
2. Sensitive read (analyst and above) — 8 read permissions on engines whose findings carry sensitive detail: vulnerability, datasec, container, dbsec, ai_security, encryption, secops, ciem.
3. Write (tenant_admin and above) — scans:create, reports:write, tenants:read/write, users:read/write, accounts:read; accounts:write and billing:read are reserved for org_admin.
4. Format and granting rules — the feature:action convention, role inheritance, and SAML group mapping.

Full role-by-permission matrix:

The viewer role gets HTTP 403 on sensitive engines — by design. Vulnerability, DataSec, CIEM, Container, DB Security, AI Security, Encryption, and SecOps may include PII column samples, vulnerability paths, or attack chains. The restriction is enforced at the engine endpoint, not just hidden in the UI — auditors with viewer accounts cannot bypass it via direct API call.

Managing users

Invite a user

The invite flow is a five-step path from admin action to active user with the right permissions.

1. Admin sends invite — Settings → Users → Invite User, selecting the role at invite time so the user lands with correct permissions on first login.
2. Email with signup link — a signed URL, valid 72 hours, single-use. Lost links must be re-issued, not extended.
3. User authenticates — existing accounts log in; new accounts set a password and enroll MFA if your tenant policy requires it.
4. Role applied — the permission set is computed and scoped to your tenant ID; an audit-log entry records inviter, invitee, role, and timestamp.
5. Access granted — the user lands in the dashboard with the assigned permissions enforced on every API call.

Change a user's role

1. Navigate to Settings → Users, find the user, and click Edit.
2. Change the role from the dropdown and click Save.

Role changes take effect within 60 seconds via session re-validation. API calls already in flight finish under the old role; the next call uses the new one.

Remove a user

1. Navigate to Settings → Users and click Remove next to the user.
2. Confirm the removal.

Removed users lose access immediately. Their findings, audit-log entries, and report attribution are retained — removal does not erase history.

Single sign-on

The platform supports SAML 2.0 (Okta, Azure AD / Entra ID, Google Workspace, JumpCloud, OneLogin, Ping Identity, ADFS) and Google OAuth (for Google-Workspace-only orgs).

SAML 2.0

The SAML flow is the standard nine-step SP-initiated handshake. The platform acts as the Service Provider (SP); your IdP authenticates the user.

SAML configuration

Start at Settings → Authentication → SSO → Configure SAML and download the Service Provider metadata XML, or configure your IdP with these SP values:

Then enter the IdP values in the platform:

Configure attribute mapping:

Finish with Test Connection, then Save.

SAML group-to-role mapping

Map IdP groups to platform roles so role changes in your IdP propagate on the user's next login. Configure under Settings → Authentication → SSO → Group Mapping:

Users get the highest-priority mapped role. Unmapped users can be assigned a default role or blocked entirely.

Google OAuth

1. Navigate to Settings → Authentication → SSO → Configure Google OAuth.
2. In Google Cloud Console, create an OAuth 2.0 Client ID with the authorized redirect URI https://api.onam.io/auth/google/callback.
3. Enter the Client ID and Client Secret in the platform.
4. Optionally restrict to your Google Workspace domain by entering it (for example, yourcompany.com) in the Allowed Domain field.
5. Click Save.

Enforce SSO (disable password login)

Once SSO is configured and tested:

1. Navigate to Settings → Authentication → SSO.
2. Toggle Require SSO for all users and confirm — all non-SSO logins are blocked from this point.

Warning: verify that at least one SSO admin can log in successfully before enabling enforcement. The platform cannot reverse the toggle without a working SSO login.

Multi-factor authentication

MFA is always enforced for platform_admin and org_admin accounts, and can be required for all users in your tenant. Navigate to Settings → Authentication → MFA and select who MFA applies to: all users, admins only, or none.

Users set up MFA on their first login after the policy is enabled. SAML SSO sessions inherit MFA from your IdP — the platform does not require duplicate MFA when the IdP already enforced it.

Audit logs

Every user-management action is recorded in the audit log and queryable via the API:

GET /api/v1/audit-logs?action=user.invite&page=1

{
  "items": [
    {
      "timestamp": "2026-07-18T10:30:00Z",
      "actor_email": "admin@yourcompany.com",
      "action": "user.invite",
      "target_email": "analyst@yourcompany.com",
      "role": "analyst",
      "ip_address": "203.0.113.1",
      "result": "success"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "has_more": false
}

Audit events include: login, logout, role change, user invite, user remove, SSO config change, scan trigger, API key create and delete, finding suppression, and framework score export. Audit logs are retained for 7 years (see Data Retention) and exportable to your SIEM via webhook or daily S3 sync.

Troubleshooting

For SSO configuration assistance: support@onam.io.

Next steps

• API Reference — how feature:action permissions are enforced on every endpoint
• Trust Center — the identity and access controls behind the platform itself
• Quickstart — invite your team after connecting your first cloud account
• Book a demo — see role-based views live with our team