SCIM 2.0: Implement discovery endpoints (ServiceProviderConfig, ResourceTypes, per-URI Schemas)
- Dominant language
- Python
- Stars
- 44.8k
- Forks
- 4.9k
- Avg merge
- 21h 10m
- Merged PRs (30d)
- 635
Description
## Summary
Sentry's SCIM 2.0 implementation currently exposes provisioning endpoints (`/Users`, `/Users/{id}`, `/Groups`, `/Groups/{id}`) and a `/Schemas` index, but does **not** implement the SCIM 2.0 service discovery endpoints defined in [RFC 7644 §4](https://datatracker.ietf.org/doc/html/rfc7644#section-4).
Specifically, the following endpoints return `404`:
- `GET /scim/v2/ServiceProviderConfig`
- `GET /scim/v2/ResourceTypes`
- `GET /scim/v2/Schemas/{schemaUri}` (per-URI lookup, e.g. `urn:ietf:params:scim:schemas:core:2.0:User`)
Reference in code: [`src/sentry/api/urls.py`](https://github.com/getsentry/sentry/blob/master/src/sentry/api/urls.py) only registers `Users`, `Users/{id}`, `Groups`, `Groups/{id}`, and `Schemas` (index only).
## Why this matters
Several Identity Governance and Administration (IGA) platforms run a SCIM 2.0 compliance pre-flight against the target service before allowing an integration to be enabled. These pre-flight validators follow RFC 7644 strictly and require:
1. `ServiceProviderConfig` to advertise supported features (filter, patch, bulk, sort, etag, auth schemes).
2. `ResourceTypes` to enumerate supported resources (User, Group).
3. Per-URI `/Schemas/{uri}` lookups to retrieve attribute definitions for each resource.
When these endpoints return `404`, the validator marks the service as **not SCIM 2.0 compliant** and blocks the integration from being configured, even though the actual provisioning endpoints work correctly against Okta and Microsoft Entra ID (which hardcode the schemas client-side and skip discovery).
## Example validator output
```
Service is not SCIM 2.0 compliant.
- HTTP GET on .../scim/v2/ServiceProviderConfig failed: not found (404).
- HTTP GET on .../scim/v2/ResourceTypes failed: not found (404).
- User is not present in ResourceTypes
- Group/Role/Entitlement is not present in ResourceTypes
- HTTP GET on .../scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User failed: not found (404).
```
## Proposed solution
Implement the three missing read-only endpoints, scoped per organization under the existing `/api/0/organizations/{org_slug_or_id}/scim/v2/` prefix:
1. **`GET /ServiceProviderConfig`** returning a static document describing Sentry's actual capabilities (e.g. `filter.supported = true` with `eq` only, `patch.supported = true`, `bulk.supported = false`, `etag.supported = false`, bearer token auth scheme).
2. **`GET /ResourceTypes`** returning entries for `User` and `Group`, mapped to the schema URIs already defined in `src/sentry/core/endpoints/scim/constants.py` (`SCIM_SCHEMA_USER`, `SCIM_SCHEMA_GROUP`).
3. **`GET /Schemas/{schemaUri}`** returning the per-URI schema document. The schema definitions already exist in `src/sentry/core/endpoints/scim/schemas.py` (`SCIM_USER_ATTRIBUTES_SCHEMA`, `SCIM_GROUP_ATTRIBUTES_SCHEMA`), so this is largely a routing addition that returns the matching object by `id`.
All three endpoints are read-only and require no new persistent state, so the implementation cost is relatively low.
## Acceptance criteria
- [ ] `GET /scim/v2/ServiceProviderConfig` returns a `200` with a valid SCIM `ServiceProviderConfig` resource.
- [ ] `GET /scim/v2/ResourceTypes` returns a `200` with `User` and `Group` resource type entries.
- [ ] `GET /scim/v2/Schemas/{schemaUri}` returns a `200` for the User and Group core schema URIs and a SCIM-compliant `404` for unknown URIs.
- [ ] Documentation updated at https://docs.sentry.io/api/scim/ and https://docs.sentry.io/organization/authentication/sso/ to reflect full SCIM 2.0 discovery support.
- [ ] Existing Okta and Entra ID integrations continue to work without changes.
## References
- [RFC 7644 §4 Service Provider Configuration Endpoints](https://datatracker.ietf.org/doc/html/rfc7644#section-4)
- [RFC 7643 SCIM Core Schema](https://datatracker.ietf.org/doc/html/rfc7643)
- Original support conversation: https://app.intercom.com/a/inbox/onh0p2wm/inbox/admin/9850682/conversation/215474146388601?view=List
Contributor guide
Assessment
This issue has not been assessed yet.