SSO and SCIM Provisioning

Configure enterprise single sign-on and directory-driven observity.ai access.

observity.ai supports OIDC single sign-on and SCIM 2.0 provisioning on Enterprise plans. Use SSO to authenticate users with your identity provider, and use SCIM to create, update, deactivate, and group-map observity.ai access from your directory.

Prerequisites

Enterprise plan with SSO and SCIM enabled
observity.ai organization admin access
Identity provider admin access for Okta, Microsoft Entra ID, or another OIDC and SCIM 2.0 provider
A verified email domain for the users who should sign in through SSO

Configure OIDC SSO

In observity.ai, open Settings > Single Sign-On (SSO) and copy the Redirect URI into your identity provider as an allowed callback URL. Then enter:

Field	Description
Issuer URL	The base issuer URL from your identity provider.
Email Domain	The domain that should be routed to your SSO provider.
Client ID	The OIDC application client ID.
Client Secret	The OIDC application client secret. Leave blank later unless rotating the secret.
Discovery Endpoint	Optional OIDC discovery document URL. observity.ai defaults to `{issuer}/.well-known/openid-configuration`.

Use the openid, email, and profile scopes in your identity provider. Configure the provider to release email, given name, family name, and subject identifier claims.

Provider-specific setup guides:

Configure SCIM

In the same observity.ai settings page, use the SCIM Provisioning section:

Copy the SCIM Base URL into your identity provider as the tenant or base URL.
Generate a SCIM bearer token and store the full token immediately. observity.ai only shows it once.
Enable the SCIM endpoint.
Set the default observity.ai role for provisioned users.
Enable Require SCIM provisioning for SSO access after your pilot users have synced successfully.
Push groups from your identity provider and map them to observity.ai roles.

Supported SCIM Resources

observity.ai implements SCIM 2.0 endpoints under:

/api/scim/v2/{organizationId}

Supported endpoints:

Endpoint	Methods	Purpose
`/ServiceProviderConfig`	`GET`	Identity provider capability discovery.
`/Users`	`GET`, `POST`	List, find, and provision users.
`/Users/{userId}`	`GET`, `PUT`, `PATCH`, `DELETE`	Read, update, deactivate, or remove a provisioned user.
`/Groups`	`GET`, `POST`	List, find, and provision groups.
`/Groups/{groupId}`	`GET`, `PUT`, `PATCH`, `DELETE`	Read, update, deactivate, or remove a provisioned group.

Supported filters:

Users: userName eq "email@example.com" and externalId eq "idp-user-id"
Groups: displayName eq "observity.ai Admins" and externalId eq "idp-group-id"

Supported PATCH operations:

User active, name, and displayName
Group displayName and members

Role Mapping

observity.ai supports three organization roles for provisioned users:

Role	Access
Viewer	Read-only access to reports and organization data allowed by product permissions.
Member	Standard user access for discovery and reporting workflows.
Admin	Organization administration, including SSO, SCIM, connectors, members, and audit logs.

When a user belongs to multiple mapped SCIM groups, observity.ai applies the highest role in this order:

admin > member > viewer

If no mapped group applies, observity.ai assigns the configured default role.

Recommended Enterprise Controls

Turn on assignment-required access in your identity provider so only assigned users and groups can sign in.
Push groups for role ownership instead of assigning elevated access user-by-user.
Enable Require SCIM provisioning for SSO access once initial user sync is complete.
Rotate the SCIM token on your normal credential rotation schedule and after any identity provider admin turnover.
Deactivate users through your identity provider instead of manually removing them in observity.ai.
Review observity.ai audit logs after rollout to confirm provisioning, role changes, SSO joins, and token rotations are recorded.

Troubleshooting

Symptom	Likely Cause	Resolution
SCIM requests return `401`	Missing or stale bearer token	Generate a new token in observity.ai and update the identity provider.
SCIM requests return `403`	SCIM is disabled or the plan does not include SCIM	Enable SCIM or confirm the organization is on Enterprise.
User sync returns `409`	The identity provider sent a duplicate `externalId` or email	Confirm each directory user has a stable unique identifier.
Users can authenticate but cannot join	Require SCIM provisioning for SSO access is enabled before the user is active in SCIM	Sync or reactivate the user from the identity provider.
Group role does not apply	The group has not been pushed or mapped in observity.ai	Push the group, then map it in Settings > Single Sign-On (SSO).

Security Notes

SCIM bearer tokens are stored hashed in observity.ai. The full token is shown only during generation or rotation. SCIM configuration changes and token rotations are written to the audit log for enterprise review.

SSO and SCIM Provisioning

On this page