SCIM (System for Cross-domain Identity Management) in Domo

Intro

The System for Cross-domain Identity Management (SCIM) is a standard that defines API endpoints that systems can use to manage identity. With an SSO integration, Domo receives information about new or updated users only when they log into Domo. However, with SCIM, you can configure your identity provider (IdP) to create and/or update users and groups in Domo when those users and groups are created and modified in your IdP.

Note: To learn more about SCIM, see the IETF protocol document .

This article describes how to get started with SCIM in Domo.

Tip: Learn more about implementing SSO for Domo and other security topics in the Knowledge Base.

---

Prerequisites

Domo’s SCIM endpoints use header-based authorization with a Domo access token.

Domo’s SCIM endpoints accept either of the two authorization headers, both of which require access tokens:

• Authorization: Bearer < Domo Access Token >
• X-Domo-Developer-Token: < Domo Access Token >

Learn how to generate an access token.

Configure Required Grants

We recommend that you create a SCIM Integration custom role and user:

1. Create a “SCIM Integration Role” as a custom role in your Domo instance — This role can be assigned only the grants required to support your intended usage of the SCIM integration (see required grants below). Learn how to create and define custom roles.
2. Create a “SCIM Integration User” in your Domo instance and assign it to the SCIM Integration Role — Domo’s SCIM endpoints require authorization using a Domo access token, and access tokens are associated with specific Domo users. Taking this approach, the access token used in the SCIM integration can be assigned to the SCIM Integration User.

Whether or not you create this recommended user and role, the owner of the access token used in the SCIM integration must have the following grants enabled:

• Manage All Users — This grant allows the holder to create, edit, and delete any user and reset their password.

• Manage All Roles — This grant allows the holder to create, edit, and delete custom roles and assign any role to any user.

• Manage All Groups — This grant allows the holder to manage group settings, modify Ad Hoc Domo groups, and create and manage Directory groups via SCIM.

  Note: This grant is not required if you don’t intend to use the SCIM Groups endpoints or the group-related attributes in the SCIM Users endpoint.
  Note: These are all admin-level grants, included automatically with the Admin system role, and allow you to add and manage all aspects of users, including setting roles and changing passwords.

Learn how to add these grants to a custom role.

---

Synchronize Directory Groups

Domo directory groups (groups defined in the IdP and created and managed in Domo via SSO or SCIM integration) can be created, managed, and deleted via SSO and SCIM. The SCIM APIs only function on directory groups. This means that groups created via SCIM are always directory groups, and the Get Group endpoint only returns information about directory groups. Learn more about directory groups and other group types in Domo.

Domo’s SCIM integration functions in the context of the Domo user who owns the Domo Access Token used by the SCIM integration. (See our recommendations for the SCIM Integration User above.) To allow Domo directory groups to be managed via SCIM, the Domo SCIM Integration User must be designated in Groups Settings as the user permitted to manage directory groups.

Follow these steps to designate the SCIM Integration User in Group Settings:

1. Go to Admin > Governance > Groups.

2. Select Group Settings (gear icon).

   

3. In the modal that displays, use the dropdown to choose the SCIM Integration User and save your changes.

   

---

Review Supported Endpoints

Domo’s SCIM implementation supports many standard endpoints. The endpoint information provided in the sections below is to help you configure your IdP.

For details of what is required with each action, refer to the SCIM spec .

Endpoint root:

{YourDomoSubdomain}.domo.com/api/identity/v1/scim

Configure Schemas

The following configuration and schema endpoints are supported in Domo:

Endpoint Name	Description	Endpoint
Get Service Provider Configuration	Retrieves the SCIM features and functionality supported by Domo.	GET /ServiceProviderConfig
Get Schemas	Retrieves a detailed list of supported SCIM schemas.	GET /Schemas
Get User Schemas	Retrieves the user schemas.	GET /Schemas/User

Manage Users

The following user endpoints are supported in Domo:

Endpoint Name	Description	Endpoint
Get Users	Retrieves all users with different request parameters to filter users. The following request and filter parameters are supported: Filter, requestedAttributes (comma-separated list of strings), startIndex (offset), count (limit), sortBy (choose a user attribute to sort by), sortOrder (ascending or descending)	GET /Users
Get User	Retrieves a user specified by their Domo userId. The requested attributes can be passed in as a comma-separated list via query parameters named “attributes.” Note that some attributes are always returned.	GET /Users/{userId} Examples: Returns a user with the phoneNumber attribute: /Users/{userId}?attributes=phoneNumbers Returns a user with all Domo attributes, including custom attributes: /scim/Users/{userId}?attributes=_all
Put User	Updates a user by Domo userId. The user’s existing attributes will be completely replaced by the attributes specified in the PUT request. If you need to update partially existing users, use the PATCH user endpoint.	PUT /Users/{userId}
Patch User Beta	Partially updates a user’s attributes as specified in the request body. Most user attributes can be added, replaced, or removed.	PATCH /Users/{userID}
Delete User	Deletes the specified Domo user. Important: If a user owns Domo DataSets or DataFlows, the user cannot be deleted via SCIM. This is because Domo requires all DataSets and DataFlows to have owners and requires ownership of those objects to be reassigned before the owner can be deleted. Important: Setting the “active” attribute to false via a PUT or PATCH request also deletes the user and is subject to the same restriction—deletion fails if the user owns DataSets or DataFlows.	DELETE /Users/{userId}
Post User	Creates a user in Domo.	POST /Users

Examples

POST /Users

{
  "schemas":[
		"urn:ietf:params:scim:schemas:core:2.0:User",
		"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
		"urn:ietf:params:scim:schemas:extension:domo:2.0:User",
		"urn:ietf:params:scim:schemas:extension:custom:2.0:User"
	],
	"userName": "[e-mail]",
	"roles": [
		{
			"type": "primary",
			"value": "4"
		}
	],
	"displayName": "John Smith",
	"active": true,
	"locale": "en-US",
	"title": "Systems Manager",
	"emails": [
		{
			"value": "[e-mail]",
			"type": "primary"
		},
		{
			"value": "[e-mail]",
			"type": "alternate"
		}
	],
	"phoneNumbers": [
		{
			"type": "work",
			"value": "555-123-4567"
		},
		{
			"type": "mobile",
			"value": "555-888-7777"
		}
	],
	"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
		"employeeNumber": "123456",
		"department": "Marketing",
		"manager": {
			"value": "6471235"
		}
	},
	"urn:ietf:params:scim:schemas:extension:domo:2.0:User": {
		"employeeLocation": "AZ Complex",
		"hireDate": "2021-03-26"
	},
	"urn:ietf:params:scim:schemas:extension:custom:2.0:User": {
		"customAttributes": [
			{
				"key": "building",
				"values": "Building A"
			},{
				"key": "alternateBuildings",
				"values": [
					"Building B",
					"Building C"
				]
			}
		]
	}
}

PUT /Users/{USER_ID}

This deletes a user via PUT

{
  "active": false,
}

PATCH /Users/{USER_ID}

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "emails",
      "value": [{
        "type": "primary",
        "value": "[e-mail]"
      }],
    },
    {
      "op": "Replace",
      "path": "urn:ietf:params:scim:schemas:extension:custom:2.0:User:customAttributes[key eq \"offices\"]",
      "value": ["NY", "CA"]
    }
  ]
}

---

Manage Groups

The following group endpoints are supported in Domo:

Endpoint Name	Description	Endpoint
Get Group	Get a group by ID.	GET /Groups/{groupID}
Post Group	Create a group in Domo.	POST /Groups
Put Group	Update a group—group definition in Domo is completely replaced by the new group definition.	PUT /Groups/{groupId}
Patch Group	Partially updates a group’s attributes. Note: Unlike PATCH for users, PATCH for groups only supports the following structure: { "op": "Replace|Add|Remove", "path": "attributePath", "value": value }. path is always required and its value is case-sensitive. Removing group attributes is not supported, except for members. value is optional for the members path in a “Remove” op. If provided, must be an array of objects each containing a “value” property with the Domo user ID (for example, [{"value": 84173534}]). For the Remove op, if the value property is not provided, all members will be removed from the group. The $ref attribute is ignored.	PATCH /Groups/{groupID}
Delete Group	Delete a group.	DELETE /Groups/{groupID}

Examples

POST /Groups

{
	"schemas": [
		"urn:ietf:params:scim:schemas:core:2.0:Group",
		"urn:ietf:params:scim:schemas:extension:domo:2.0:Group"
	],
	"displayName": "US - Marketing",
	"members": [
		{
			"value": "1201764328"
		}
	],
	"urn:ietf:params:scim:schemas:extension:domo:2.0:Group": {
		"domoDisplayName": "Marketing",
		"description": "Members of the US-based marketing team."
	}
}

PATCH /Groups/{GROUP_ID}

This removes all members from a group

{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:PatchOp"
	],
	"Operations": [
		{
			"op": "Remove",
			"path": "members"
		}
	]
}

PATCH /Groups/{GROUP_ID}

This replaces all members of a group with those provided

{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:PatchOp"
	],
	"Operations": [
		{
			"op": "Replace",
			"path": "members",
			"value": [
				{
					"value": "1201764328"
				}
			]
		}
	]
}

---

Configure Your IdP

The SCIM integration between your IdP and Domo is configured on the IdP side. To get started, refer to the documentation from your IdP.

Map Schemas and Attributes

During configuration, you must configure which user attributes and group properties are synchronized to Domo from your IdP. Domo’s SCIM endpoints map elements from six SCIM schemas.

These schemas and their elements are mapped to various Domo user and group attributes. The tables below list the Domo user and group attribute names and the corresponding SCIM schema and attribute.

Map User Attributes

Domo Attribute	Schema	SCIM Element	Notes
User Name (Required) This is the user’s email address, which is the unique identifier for the user in Domo.	urn:ietf:params:scim:schemas:core:2.0:User	userName
Name	urn:ietf:params:scim:schemas:core:2.0:User	displayName	Domo uses displayName for the user’s name. The “name” complex attribute (givenName, familyName, etc.) is not supported and will be ignored.
Email (Required)	urn:ietf:params:scim:schemas:core:2.0:User	emails An array of complex of email and type. Type of “work” maps to Domo user primary email address.	For Okta: specify the external name as emails.^[primary == true].type For Entra: specify emails[type eq "work"].value
Alternate email	urn:ietf:params:scim:schemas:core:2.0:User	emails An array of complex of email and type. Type of “alternate” maps to Domo user alternate email address.	For Okta: specify the external name as emails.^[primary == false].type For Entra: specify emails[type eq "alternate"].value
Active Indicates whether the user is active in Domo. Important: Setting to false deletes the Domo user.	urn:ietf:params:scim:schemas:core:2.0:User	active
Role Domo supports a single role per user. Role is optional on both create (POST) and update (PUT).	urn:ietf:params:scim:schemas:core:2.0:User	roles - Single-valued array of complex of role id (required) and role name (optional; ignored by Domo). - Domo accepts only one role per user, so the roles array must contain only a single value.	For Okta: specify roles.^[primary == true].id
Employee ID	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	employeeNumber
Hire date	urn:ietf:params:scim:schemas:extension:domo:2.0:User	hireDate	Domo stores this field as a date. If your IdP sends a date-time value, Domo will accept and convert it, but the type mismatch may cause your IdP to evaluate the field as changed and re-send it on every sync. To prevent this, convert the field to a date type in your source system before mapping it.
Title	urn:ietf:params:scim:schemas:core:2.0:User	title
Department	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	department
Location	urn:ietf:params:scim:schemas:extension:domo:2.0:User	employeeLocation
Mobile phone	urn:ietf:params:scim:schemas:core:2.0:User	phoneNumbers Array of complex of phone number and type. Type of “mobile” maps to Domo user mobile phone number.
Desk phone	urn:ietf:params:scim:schemas:core:2.0:User	phoneNumbers Array of complex of phone number and type. Type of “work” maps to Domo user desk phone number.
Locale	urn:ietf:params:scim:schemas:core:2.0:User	locale
Timezone	urn:ietf:params:scim:schemas:core:2.0:User	timezone
Group	urn:ietf:params:scim:schemas:core:2.0:User	groups / {value, display} Where value is the ID of the group in Domo and display is the group name as defined in the IdP.
Organization	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	organization
Manager	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User	manager {value, display} Complex of value (Domo user ID) and display (optional, manager name, ignored by Domo).
All custom attributes Tip: Learn more about Domo custom attributes.	urn:ietf:params:scim:schemas:extension:custom:2.0:User	customAttributes: [{key, values}] Array of complex of key (the attribute key as defined in Domo) and values (the user attribute values).	Custom attributes must be defined in Domo before they can be populated via SCIM, and the key in the SCIM must match the attribute key in Domo exactly (case-sensitive). For example, a Domo attribute of building is defined: For Okta - External name: customAttributes.^[key == building].values For Entra - User attribute name: urn:ietf:params:scim:schemas:extension:custom:2.0:User:customAttributes[key eq "building"].value

Map Group Attributes

Domo Attribute	Schema	SCIM Attribute	Notes
Directory Name The group name as defined in the IdP.	urn:ietf:params:scim:schemas:core:2.0:Group	displayName
Domo Group Display Name The group name in Domo that is most readily accessible to Domo users and is presented to users throughout the product, such as when sharing content or viewing card ownership.	urn:ietf:params:scim:schemas:extension:domo:2.0:Group	domoDisplayName
Description	urn:ietf:params:scim:schemas:extension:domo:2.0:Group	description
Group Membership	urn:ietf:params:scim:schemas:core:2.0:Group	members An array of complex of value (the group member Domo user ID) and display (optional, group member name, ignored by Domo).

FAQs

1. Why does Okta’s SCIM sync for groups sometimes remove all members or change membership unexpectedly?
   • Okta requires different groups for assignment and membership. See Okta’s support site for details on this limitation.
2. Why is Okta’s SCIM sync not working reliably after pointing my Okta app at a different Domo instance?
   • Okta stores the “external id” (ID of the user in Domo, for example) within the Okta app. If the Okta app is pointed to a different Domo instance where the ID’s of your users and groups are different, Okta can no longer reconcile those which may result in unexpected behavior. This is a known limitation with Okta’s SCIM implementation. Because of that, we recommend creating a new Okta app for each Domo instance and not changing the target instance URL after creation.