Skip to main content
Gradial separates login from provisioning:
  • SSO answers “can this person log in?”
  • SCIM 2.0 answers “should this person have Gradial access, what role should they have, and which workspaces should they see?”
SCIM is one-way: your identity provider (IdP) pushes user and group changes into Gradial. Gradial never writes changes back to the IdP.
SSO alone does not silently create a Gradial account. A user must be provisioned (through SCIM, a manual invite where allowed, or another valid linking path) before they can log in. An unprovisioned SSO user sees a clear “account not provisioned” error rather than ending up with a silent orphan account.

​
How to Enable SCIM

Organization owners and admins configure SCIM under Settings → Developer → SCIM Provisioning.
Gradial’s SCIM implementation is currently validated for Microsoft Entra ID only. See Microsoft Entra ID Setup for the Entra-specific steps.

​
Connect to your IdP

1

Enable SCIM in Gradial

Toggle SCIM provisioning on.
2

Create a SCIM token

Create a new SCIM token in Gradial and copy it, together with the SCIM base URL.
3

Update your IdP

Update the secret token and the base URL in your identity provider, test the connection, and save.

​
Required attributes

Map the following attributes in your IdP so all SCIM features work once enabled. Users
  • userName: a unique sign-in name for the user, such as the Entra user principal name (UPN).
  • externalId: the user’s IdP object ID. In Entra, this must be objectId.
  • emails: one email, marked primary. This is the user’s email in Gradial. It must be a mailbox that receives mail, because Gradial sends notifications to it, and it must match the email the user signs in with through SSO.
  • displayName: the user’s name in Gradial.
  • active: Gradial deprovisions the user when the IdP sends false.
  • roles: the user’s organization role (admin, member, or viewer), sent as the primary role. Only needed if you sync organization roles from your IdP.
Groups
  • displayName: the group’s name in Gradial.
  • externalId: the group’s IdP object ID. In Entra, this must be objectId.
  • members: the group’s members.

​
User provisioning

User provisioning is managed via SCIM by your IdP. To test, assign a user to the Gradial app in your IdP and provision them on demand (in Entra, Provision on demand). The user should appear on the People page with an Identity provider badge.

​
Organization role syncing

Gradial supports managing users’ organization roles (not to be confused with workspace roles) from your IdP.
  • Turn on Sync roles from Identity Provider in the SCIM Provisioning section. It is off by default, and while it is off Gradial ignores roles sent by the IdP.
  • The IdP sends the role in roles (see Required attributes). See Organization Role Sync for how other values are handled.
  • In Entra, map the user’s app role to that attribute. If your app-role names differ from Gradial’s, translate them with the Switch expression in Microsoft Entra ID Setup.

​
Workspace mapping

Gradial supports mapping IdP groups to workspaces.
  • Enable group provisioning in your IdP (in Entra, Provision Microsoft Entra ID Groups).
  • Once a group is synced to Gradial, map it to a workspace under Settings → Developer → SCIM Group Mappings. This section appears once SCIM provisioning is on.
  • Each mapping sets the workspace role (viewer, member, or admin) the group’s members get in that workspace. See Workspace Access Through Group Mappings for the role rules.

​
SCIM Tokens

Gradial issues a dedicated bearer token for SCIM. Treat it like any other sensitive credential.
  • Prefix: gxs_
  • Scope: exactly one organization — a token cannot reach any other organization
  • Visibility: shown once at creation, so copy it immediately
  • Expiration options: 30, 60, 90, 180, 365 days, or no expiration
  • Usage: sent in the Authorization: Bearer <gxs_...> header

​
Token rotation

1

Create a new token

Create a new SCIM token in Gradial and copy it.
2

Update your IdP

Update the secret token in your IdP, test the connection, and save.
3

Revoke the old token

Revoke the previous token in Gradial.

​
Base URL and Discovery

Base URL: https://<your-gradial-host>/api/scim/v2 Discovery endpoints are served without authentication, because IdP connector setup may probe them before sending a bearer token:
  • GET /ServiceProviderConfig
  • GET /Schemas
  • GET /ResourceTypes
Discovery advertises bearer token authentication, PATCH support, User and Group resource types, and Gradial’s optional organization-role extension schema. Bulk operations, password changes, and sorting are not supported.

​
Supported Endpoints

​
Users

​
Groups

​
User Provisioning Behavior

​
Creating users (POST /Users)

  • A new email creates a Gradial user, a SCIM link, and organization membership.
  • If the email already belongs to a Gradial user in another organization, that existing global identity is linked into this organization. Access in other organizations is not changed.
  • If a SCIM link for that user is inactive, the user is reactivated.
  • If an active SCIM user already exists in the same organization, the request returns a uniqueness conflict.
  • The user’s email comes from emails, which must contain one email, marked primary.

​
Updating users (PATCH /Users/{id})

Supported attributes:

​
Deprovisioning users

Deprovisioning can be triggered by PATCH active=false (the common Entra path) or by DELETE /Users/{id}. Both have the same effect:
  • The user’s organization membership is removed.
  • The user’s SCIM group memberships are removed.
  • The user’s non-owner workspace memberships (in that organization) are removed.
  • The user’s sessions scoped to that organization are cleared.
Owners cannot be deprovisioned by SCIM. Removing an owner returns a conflict — the owner must be downgraded or transferred manually first.

​
Organization Role Sync

SCIM can set the organization role of SCIM-managed users to admin, member, or viewer. owner is not SCIM-manageable: assigning it is rejected with a conflict, and owners always remain Gradial-managed. Roles are read from two places:
  1. The standard SCIM roles array, especially roles[primary eq "True"].value
  2. Gradial’s extension schema: urn:gradial:params:scim:schemas:extension:organization-role:2.0:User with organizationRole
Standard roles wins when present and parseable. Unknown role values are ignored. Whether the IdP or Gradial controls a SCIM-managed member’s primary organization role depends on the Sync roles from Identity Provider setting:
  • Enabled — the primary organization role can only be changed in the identity provider. The People page shows these rows with disabled role controls.
  • Disabled — Gradial manages the role and ignores the role value sent by the provider.
Additional access (Brand Manager, Designer) is managed in Gradial either way, separately from a SCIM-controlled primary role.

​
Workspace Access Through Group Mappings

SCIM does not let the IdP directly create arbitrary Gradial groups or workspaces. Instead, access flows through admin-managed mappings:
  1. The IdP provisions SCIM group identities and memberships.
  2. A Gradial admin maps a provisioned IdP group to a Gradial workspace (and a workspace role) under Settings → Developer → SCIM Group Mappings.
  3. Gradial reconciles workspace membership from the mapping and the latest group membership facts.
Mapping fields:
  • IdP Group — a previously provisioned SCIM group
  • Workspace — an existing workspace, or “create or reuse a workspace from this IdP group”
  • Workspace role — viewer, member, or admin

​
Workspace role rules

  • owner is not a SCIM-managed workspace role. Workspace owner rows are always Gradial-managed and are never inserted over, updated, downgraded, or deleted by SCIM.
  • Non-owner workspace membership and roles are IdP-managed for mapped workspaces.
  • An IdP group can map to several workspaces, each with its own role, and several IdP groups can map to the same workspace.
  • If a user is in multiple mapped groups for the same workspace, the highest role wins: admin > member > viewer.
  • If a user is removed from an admin group but remains in a member/viewer group for the same workspace, Gradial downgrades rather than revokes.
  • If a user is absent from every mapped group for that workspace, Gradial removes their non-owner workspace membership.

​
Mapping lifecycle

  • Creating a mapping immediately reconciles existing SCIM group membership.
  • Deleting a mapping reconciles the affected workspace and can remove access for users whose only path was that mapping. The workspace itself is not deleted.
  • Re-adding a mapping can reuse a workspace previously associated with that IdP group.
  • The mapping UI shows an impact preview before saving (grants, revokes, and role changes).
For SCIM-mapped workspaces, manual changes to non-owner workspace members are blocked by the backend, not just disabled in the UI.

​
Manual Invites in SCIM-Managed Organizations

When SCIM provisioning is enabled for an organization:
  • Local email/password signup and manual invites cannot create or grant initial non-owner access in that organization.
  • Owners are still managed in Gradial.
  • The People page indicates which members are IdP-provisioned versus locally provisioned, so admins can verify that all non-owner access is coming through SCIM.

​
Microsoft Entra ID Setup

The steps below are the Entra-specific setup.
1

Enable SCIM in Gradial

An organization owner or admin turns on SCIM Provisioning under Settings → Developer. Create a SCIM token and copy it immediately.
2

Configure Entra admin credentials

In Microsoft Entra admin center → Enterprise applications → Gradial → Provisioning → Admin credentials:
  • Provisioning Mode: Automatic
  • Tenant URL: https://<your-gradial-host>/api/scim/v2
  • Secret Token: your gxs_... token
Click Test Connection, then save.
3

Configure user mappings

In Mappings → Provision Microsoft Entra ID Users, map all of the attributes below. externalId must be mapped to objectId, and mail must match the email the user signs in with through SSO.
4

Enable group provisioning

In Mappings, enable Provision Microsoft Entra ID Groups. This is required for Gradial workspace access: without it, Gradial receives users but no groups, and the Gradial group-mapping picker will be empty.Map all of the group attributes below:
5

Configure the role mapping

Only needed if you sync organization roles from Entra. The final SCIM value must be one of admin, member, or viewer.Simplest option: define Entra app-role values exactly as admin, member, and viewer, then map:
  • Mapping type: Expression
  • Expression: SingleAppRoleAssignment([appRoleAssignments])
  • Target attribute: roles[primary eq "True"].value
  • Apply this mapping: Always
If your Entra app-role names differ, use an expression that translates them to Gradial’s vocabulary, for example:
Entra Switch comparisons are case-sensitive. Assign only one app role per user for this mapping — SingleAppRoleAssignment is a single-role helper.
6

Assign users and groups

In Users and groups, assign the users and groups that should have Gradial access.Set Provisioning Status to On. Use Provision on demand to test a single user and a single group before letting the full cycle run.
7

Map groups to workspaces in Gradial

After Entra provisions groups, a Gradial admin maps each Entra group to a Gradial workspace under Settings → Developer → SCIM Group Mappings, choosing a workspace role of viewer, member, or admin.

​
Troubleshooting

The group picker only shows IdP groups that Gradial has actually received. If it is empty:
  1. Confirm SCIM provisioning is enabled in Gradial.
  2. Confirm the SCIM token and base URL in Entra match the intended Gradial organization.
  3. Confirm the IdP group is assigned to the Entra enterprise application.
  4. Confirm Entra provisioning has Provision Microsoft Entra ID Groups enabled. This is a common root cause: Entra provisions users but never sends group calls.
  5. Use Provision on demand for the group, or restart provisioning.
  6. Wait for the next Entra polling cycle if not forcing a sync.
This is expected. Provision the user through SCIM first (assign them to the Entra enterprise app and run provisioning), then have them log in again.
Gradial requires an email claim to complete SSO. Azure AD only emits the email claim when the user’s mail attribute is populated — it does not synthesize one from the user principal name (UPN), and adding email to the app registration’s optional claims does not fix this on its own. Accounts without mail (commonly service, shared, or non-mailbox accounts) therefore see this error, while users with a normal mailbox sign in normally — which is why it often affects only a subset of users.Fix: have your Entra admin populate the mail attribute on the affected accounts.Prevention: before enabling Gradial SSO, have your Entra admin verify that every user who will sign in has a populated mail attribute. Catching mailless accounts during rollout planning is much cleaner than after a user hits the error page.
Deprovisioning removes the user’s organization membership and workspace access, so they no longer appear on the People page and cannot log in. If they still appear, check the Entra provisioning logs to confirm the deprovisioning was sent, and confirm the IdP has not reactivated or re-assigned them.
Entra can quarantine an app and slow its sync cadence if error rates are high. Check the Entra provisioning logs for failing requests, verify the SCIM token is valid and not expired, and verify the Gradial organization still has SCIM enabled. Use Provision on demand to isolate a failing user or group.

​
Current Limitations

  • SCIM cannot assign or remove owners, at either the organization or workspace level.