From 6be7ff58e1650affad6147fd21fc308c8e84954a Mon Sep 17 00:00:00 2001 From: Sandro Dolidze Date: Tue, 28 Jul 2026 17:11:41 +0100 Subject: [PATCH] chore(scim): document organization custom role values --- references/workspace/scim-integration.mdx | 33 +++++++++++++++++------ 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/references/workspace/scim-integration.mdx b/references/workspace/scim-integration.mdx index 87f58705..1b1db0a2 100644 --- a/references/workspace/scim-integration.mdx +++ b/references/workspace/scim-integration.mdx @@ -183,6 +183,8 @@ SCIM_ENABLED=true Replace `3675b69e-8324-4110-bdca-059031aa8da3` with your actual project UUID and adjust group names to match your Okta groups. + To assign a custom role, use the bare custom-role UUID for an organization-level custom role. For a project-level custom role, keep the project UUID prefix and use `:`. + ![](/images/references/workspace/scim-okta-role-mapping.png) @@ -262,7 +264,7 @@ SCIM_ENABLED=true Lightdash exposes a standard SCIM 2.0 API, so any SCIM-compatible client can manage users and groups — including a sync job of your own that reads from the [Google Directory API](https://developers.google.com/workspace/admin/directory) and pushes changes to Lightdash. - Use the SCIM base URL and access token from [SCIM Setup within Lightdash](#scim-setup-within-lightdash). For example, to create a user with an organization role and a project role: + Use the SCIM base URL and access token from [SCIM Setup within Lightdash](#scim-setup-within-lightdash). For example, to create a user with an organization-level custom role and a project-level custom role: ```bash curl -X POST "https://YOUR_APP_URL/api/v1/scim/v2/Users" \ @@ -274,13 +276,13 @@ SCIM_ENABLED=true "name": { "givenName": "Jane", "familyName": "Doe" }, "active": true, "roles": [ - { "value": "editor" }, - { "value": "3675b69e-8324-4110-bdca-059031aa8da3:viewer" } + { "value": "b02daf62-03e8-4fe9-bf7f-16d59a93d5d1" }, + { "value": "3675b69e-8324-4110-bdca-059031aa8da3:da116e0f-2b96-4af4-93b7-b2636a26853d" } ] }' ``` - Role `value`s follow the format described in [User Role Provisioning](#user-role-provisioning): an organization role name (e.g. `editor`), or `:` for project roles. Only the `value` field is required. + Role `value`s follow the format described in [User Role Provisioning](#user-role-provisioning). An organization-level custom role uses its bare custom-role UUID, while a project-level custom role uses `:`. Only the `value` field is required. See the [SCIM API reference](https://docs.lightdash.com/api-reference/scim/list-users) for all endpoints and payloads. @@ -347,17 +349,22 @@ We support the standard SCIM 2.0 `roles` attribute as defined in [RFC 7643](http ### Role types -Lightdash defines two role scopes: Organization and Project. Organization roles can be set to member, viewer, interactive viewer, editor, developer, or admin. Project roles can be viewer, interactive viewer, editor, developer, admin, or a [custom role](/references/workspace/custom-roles). +Lightdash defines two role scopes: Organization and Project. Both scopes support system roles and [custom roles](/references/workspace/custom-roles). + +| Scope | System role `value` | Custom role `value` | +| --- | --- | --- | +| Organization | The role name, such as `member`, `viewer`, `interactive_viewer`, `editor`, `developer`, or `admin` | The bare custom-role UUID: `` | +| Project | `:`, where `role` is `viewer`, `interactive_viewer`, `editor`, `developer`, or `admin` | `:` | - The project role values are a combination of the project id and the role identifier. + Do not prefix an organization-level custom role with the organization UUID. Its `value` is only the custom-role UUID. Project role values always combine the project UUID and role identifier. Examples: ``` [ - { + { schemas: [ScimSchemaType.ROLE], id: 'member', value: 'member', @@ -365,6 +372,14 @@ Examples: type: 'Organization', supported: true, }, + { + schemas: [ScimSchemaType.ROLE], + id: 'b02daf62-03e8-4fe9-bf7f-16d59a93d5d1', + value: 'b02daf62-03e8-4fe9-bf7f-16d59a93d5d1', + display: 'Data consumer', + type: 'Organization', + supported: true, + }, { schemas: [ScimSchemaType.ROLE], id: '3675b69e-8324-4110-bdca-059031aa8da3:viewer', @@ -389,6 +404,8 @@ Examples: The SCIM roles model is currently an [IETF draft](https://datatracker.ietf.org/doc/draft-ietf-scim-roles-entitlements), so native support to auto-discover roles via a `/Roles` endpoint varies by provider and connector. +Lightdash's `/Roles` endpoint returns system and custom roles. Organization-level custom roles use their bare custom-role UUID as `id` and `value`, with `type` set to `Organization`. Project-level custom roles use `:`, with `type` set to `Project - `. + - Okta: Does not natively auto-populate role picklists by consuming a SCIM `/Roles` endpoint. You can still provision `roles` [manually](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-add-custom-user-attributes.htm) or implement custom sync using [Okta Workflows](https://help.okta.com/wf/en-us/content/topics/workflows/workflows-main.htm) or a [custom app](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard.htm). - Microsoft Entra ID (Azure AD): Does not currently auto-discover roles from `/Roles`. Use [manual configuration](https://learn.microsoft.com/azure/active-directory/app-provisioning/customize-application-attributes) of allowed roles. - Google Cloud Identity / Workspace: Custom SCIM applications are not supported, so there is no role configuration to do in Google itself. See the [Google Workspace integration guide](#integration-guides) above for the available approaches. @@ -401,7 +418,7 @@ How to tell if your IdP supports it: - Inspect provisioning or discovery logs: if the IdP issues `GET /Roles` during discovery, it likely supports it. - If the connector supports custom discovery endpoints or schema extensions, you may be able to add `/Roles` even if it’s not built-in. -If your IdP doesn’t support `/Roles`, use the manual configuration documented in your IdP. Remember: only the `value` is required by Lightdash. +If your IdP doesn’t support `/Roles`, use the manual configuration documented in your IdP. Configure organization-level custom roles as bare custom-role UUIDs and project-level custom roles as `:`. Only the `value` is required by Lightdash. ### Lightdash Extension Schema (deprecated)