sentry-enterprise-rbac

What this skill does

# Sentry Enterprise RBAC

## Overview

Configure Sentry's Organization-Team-Project hierarchy, role assignments, SSO/SAML2 federation, SCIM automated provisioning, API token governance, and audit logging. Covers the full enterprise access control lifecycle from initial setup through ongoing compliance monitoring.

## Prerequisites

- **Sentry Business or Enterprise plan** — team-level roles, SSO, SCIM, and audit logs require Business tier or higher
- **Organization Owner or Manager role** — only these roles can configure auth, teams, and member roles
- **Identity Provider access** — admin credentials for Okta, Azure AD, or Google Workspace if configuring SSO/SCIM
- **Environment variables set:**

  ```bash
  export SENTRY_AUTH_TOKEN="sntrys_..."   # Auth token with org:admin, member:admin, team:admin scopes
  export SENTRY_ORG="your-org-slug"       # Organization slug from sentry.io/settings/
  ```

## Instructions

### Step 1 — Establish the Organization-Team-Project Hierarchy

Sentry's access model flows top-down: **Organization > Teams > Projects**. Members inherit permissions from their org-level role, then gain project access through team membership.

**Organization-level roles** define the ceiling of what a member can do:

| Role | Capabilities | Typical Use |
|------|-------------|-------------|
| **Owner** | Full control: billing, auth, members, all settings. Irremovable. | Founding eng, CTO |
| **Manager** | Manage all teams, projects, and members. No billing access. | Engineering managers |
| **Admin** | Manage integrations, projects, teams. No member management. | Tech leads, DevOps |
| **Member** | View data, act on issues, join/leave teams. Default for new users. | Individual contributors |
| **Billing** | Payment and subscription management only. No technical access. | Finance team |

**Team-level roles** (Business/Enterprise only) add granularity within teams:

| Team Role | Additional Capabilities |
|-----------|------------------------|
| **Team Admin** | Manage team membership, add/remove projects from the team |
| **Contributor** | View and act on issues in the team's projects |

A member's effective permissions are the **union** of their org-level role and all team-level roles they hold. A Member with Team Admin on "payments-team" can manage that team but cannot touch org-wide settings.

**Create the team structure:**

```bash
# Create a team
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"slug": "backend-eng", "name": "Backend Engineering"}' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/teams/" | jq '{slug, name, dateCreated}'

# List all teams with member counts
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/teams/" \
  | jq '.[] | {slug, memberCount, hasAccess}'

# Assign a project to a team (grants team members access to that project)
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/backend-eng/"

# Remove a team's access to a project
curl -s -X DELETE \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/backend-eng/"

# List which teams have access to a project
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/projects/$SENTRY_ORG/payment-api/teams/" \
  | jq '.[].slug'
```

**Manage team membership:**

```bash
# List organization members (get MEMBER_ID values)
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/" \
  | jq '.[] | {id, email, role, expired}'

# Add a member to a team
curl -s -X POST \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/teams/backend-eng/"

# Remove a member from a team
curl -s -X DELETE \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/teams/backend-eng/"

# Update a member's organization role
curl -s -X PUT \
  -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/members/$MEMBER_ID/"
```

### Step 2 — Configure SSO/SAML2 and SCIM Provisioning

SSO centralizes authentication; SCIM automates the user lifecycle. Configure SSO first, then layer SCIM on top.

**SSO/SAML2 setup — Okta example:**

1. In Okta Admin Console, create a new SAML 2.0 application
2. Set the Single Sign-On URL to: `https://sentry.io/saml/acs/{org_slug}/`
3. Set the Audience URI (SP Entity ID) to: `https://sentry.io/saml/metadata/{org_slug}/`
4. Configure attribute statements:

   | Name | Value |
   |------|-------|
   | `email` | `user.email` |
   | `firstName` | `user.firstName` |
   | `lastName` | `user.lastName` |

5. Download the IdP metadata XML or copy the metadata URL

**SSO/SAML2 setup — Azure AD:**

1. In Azure Portal > Enterprise Applications, add Sentry from the gallery
2. Configure SAML SSO with Reply URL: `https://sentry.io/saml/acs/{org_slug}/`
3. Set Identifier (Entity ID): `https://sentry.io/saml/metadata/{org_slug}/`
4. Map claims: `emailaddress`, `givenname`, `surname`
5. Download the Federation Metadata XML

**SSO/SAML2 setup — Google Workspace:**

1. In Google Admin > Apps > SAML Apps, add a custom SAML app for Sentry
2. Set ACS URL: `https://sentry.io/saml/acs/{org_slug}/`
3. Set Entity ID: `https://sentry.io/saml/metadata/{org_slug}/`
4. Map `email`, `firstName`, `lastName` attributes
5. Download the IdP metadata

**Activate in Sentry:**

1. Navigate to **Organization Settings > Auth**
2. Click **Configure** next to SAML2
3. Enter the IdP metadata URL or upload the metadata XML
4. Click **Save** then **Test SSO Login** — verify it redirects and authenticates correctly
5. Enable **Require SSO** to enforce SSO for all organization members
6. Optionally set a **Default Role** for SSO-provisioned users (typically Member)

**SCIM provisioning** automates user creation, deactivation, and group sync:

```
SCIM Base URL:  https://sentry.io/api/0/organizations/{org_slug}/scim/v2/
Authentication: Bearer token (generated in Sentry's SCIM settings page)
```

```bash
# Provision a new user via SCIM
curl -s -X POST \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[email protected]",
    "name": {"givenName": "Jane", "familyName": "Doe"},
    "emails": [{"primary": true, "value": "[email protected]", "type": "work"}],
    "active": true
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users"

# List SCIM-provisioned users
curl -s -H "Authorization: Bearer $SCIM_TOKEN" \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users?count=100" \
  | jq '.Resources[] | {id, userName, active}'

# Deactivate a user via SCIM (sets active to false)
curl -s -X PATCH \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{"op": "replace", "value": {"active": false}}]
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Users/$SCIM_USER_ID"

# Sync IdP groups to Sentry teams via SCIM Groups
curl -s -X POST \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "backend-eng",
    "members": []
  }' \
  "https://sentry.io/api/0/organizations/$SENTRY_ORG/scim/v2/Groups"
```

SCIM capabilities once connected:

- **Auto-create** users when assigned in the IdP
- **Auto-deactivate** users when removed from the IdP group
- **Sync team membership** from IdP groups to Sentry teams