如何使用我们的 SCIM API 自动化用户和群组管理

概述

用于跨域身份管理的系统 (SCIM) 是一种标准 API，用于自动化用户和群组预配/取消预配，并将用户和群组数据从客户的身份提供程序 (IdP) 更新到 Udemy Business 帐户中。许多身份提供程序（例如 Okta、Azure AD 和 OneLogin）都支持 SCIM。您还可以将 Udemy Business SCIM API 用于其他 IdP 或本土工具。

如果您的组织使用以下 IdP 之一，请参阅下面的指南，了解如何配置 SCIM：

SCIM 使用标准化的 REST API，数据格式为 JSON。Udemy Business 支持 SCIM 标准的 2.0 版。该 API 适用于 Enterprise 方案中的所有客户。

Udemy Business SCIM API 支持以下功能：

配置用户
取消配置用户（停用）
更改电子邮件地址
更改用户详细信息
配置群组
在群组中添加/移除用户

SCIM 协议说明

SCIM 协议是一种应用级 REST 协议，用于在 Web 上配置和管理身份数据。该协议是客户端-服务器协议，其中客户端是身份提供程序 (IdP)，服务器是 Udemy Business。

基本流程如下：

当客户在 IDP 中为用户授予 Udemy Business 访问权限时，IdP 会向我们发送请求，以检查特定用户是否存在于我们的数据库中。他们通过用户名或电子邮件等属性发出用户搜索请求。
如果用户不存在，则 IdP 会发送创建用户的请求。
如果用户存在，则 IdP 会发送该用户的更新请求。
如果撤销 Udemy Business 的访问权限，则 IdP 会向我们发送从我们的数据库中停用该用户的请求。
IdP 还会发送更改用户详细信息的请求。

如何访问 API？

为了获取连接到 SCIM API 的授权凭据，必须在您的 Udemy Business 帐户中通过管理 -> 设置 -> 配置 (SCIM) 页面设置 SCIM 集成。请注意：仅管理员可以访问此页面。

点击开始设置。

在下一步中，选择选择提供程序，然后选择自定义。

单击生成令牌。

在此屏幕上，单击复制以将持有者令牌复制到剪贴板。

您需要在请求中包含带有持有者令牌的授权 HTTP 标头，例如：

GET /scim/v2/Users HTTP/1.1

Host: myorganization.udemy.com

Accept: application/scim+json

Authorization: Bearer <enter you Bearer token here>

Content-Type: application/scim+json

Udemy Business SCIM API 使用 HTTP 协议，并且只能通过安全的 HTTPS 连接使用。

该 API 的基本 URL 是 https://<organization>.udemy.com/scim/v2/。

如果您正在开发一款应用来与 Udemy Business SCIM API 进行交互，建议参考本文档末尾包含的 SCIM RFC。Udemy Business SCIM API 实施符合标准。

SCIM API 端点

信息端点

这些是信息端点，用于配置客户端。他们不需要身份验证，因此您在访问这些端点时不需要包含授权标头。

GET /ServiceProviderConfig

返回有关 Udemy Business SCIM 实施的详细信息，包括支持的方法。

GET /Schemas

返回 SCIM 实施支持的架构的相关信息。支持的架构是用户和群组。

GET /Schemas/Users

返回支持用户资源的所有属性。

GET /Schemas/Groups

返回支持群组资源的所有属性。

用户端点

您可以使用这些端点列出用户、按属性筛选、添加新用户、更新用户信息或停用用户/将用户匿名。请记住，您只能访问使用 SCIM API 创建的用户，在 Udemy Business 中创建的用户将不可用，除非您通过 SCIM 进行调节。下面提供了有关调节的更多详细信息。

支持的属性

SCIM 属性	是否必填？	说明
用户名	是	IdP 的用户名。必须唯一。
姓名，{ givenName, familyName }	否	用户的名字和姓氏。虽然这不是必填属性，但我们建议始终指定这些属性，因为这样便于轻松识别用户。
电子邮件 [type=”work”]]['value’]	是	用户的电子邮件地址，必须唯一
活跃	是	标记停用/重新激活用户
职称	否	用户的职称，即“高级工程师”
外部 ID	是	IdP 用户的外部 ID。必须唯一。

请注意：如果您指定不在此列表中的任何其他属性，系统将会忽略相关属性。

GET/Users

返回用户的分页列表，默认情况下每页 12 个用户。您可以传入 count 和 startIndex 参数以对结果集进行分页。例如：

GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

Host: myorganization.udemy.com

Accept: application/scim+json

Authorization: Bearer <enter you Bearer token here>

startIndex 是当前结果列表集中第一个结果从 1 开始的索引（偏移）
count 是列表响应页面中返回的资源数量（限制）。您可以在单个请求中检索至多 1000 个用户。如果省略此项目，则默认为 12。

GET /Users?filter=

此端点用于按特定属性筛选用户。例如，可以根据用户名属性进行搜索：

GET /Users?filter=userName eq "gloria.graynor”

请注意：在上述示例中，您需要对 URL 参数进行 URL 编码，因此 URL 将变为：
GET /Users?filter=userName%20eq%20%22gloria.graynor%22

此时将返回用户资源列表。如果没有任何结果，将返回一个空列表。

支持的筛选条件如下：

用户名
外部 ID
电子邮件 [type eq=”work”]

支持的运算符如下：

响应：

HTTP 状态代码 200 和成功的实体列表
如果提供了不受支持的筛选条件，则会返回 HTTP 状态代码 501

POST /Users

此端点用于在 Udemy Business 中创建（配置）新用户。

响应将包含一个 id 属性，在所有后续请求中引用此用户时应当使用该属性。

请注意：

以这种方式创建的新用户在该用户首次登录之前不会使用许可证。
如果此用户已有待处理的邀请，则此时将使用该邀请。
系统会将用户添加到群组，根据邀请中指定的条件分配适当的角色/课程作业。
尝试创建 Udemy Business 中已存在的用户将导致该用户变为由 SCIM 管理（在“管理用户”页面中显示一个小链接图标）。请注意：用户的状态和许可证使用情况不会更改。如果用户处于活跃状态，将保持活跃状态；如果用户已停用，将保持停用状态。

响应：

HTTP 状态代码 201 和成功的用户资源
如果组织中已存在具有相同用户名的成员，则会返回 HTTP 状态代码 409
如果请求未通过验证，则会返回 HTTP 状态代码 400，响应正文中会显示错误详细信息

GET /Users/<id>

此端点用于检索指定用户的用户详细信息。上述请求中的 id 参数是在使用 SCIM 创建用户或列出所有现有用户时返回的唯一标识符。

响应：

HTTP 状态代码 200 和成功的用户资源
如果未找到用户，则会返回 HTTP 状态代码 404

PUT /Users/<id>

此端点用于替换（覆盖）Udemy Business 中的用户详细信息。如果已指定，活跃属性可用于停用或重新激用户。

响应：

HTTP 状态代码 200 和更新的用户资源
如果用户不存在，则会返回 HTTP 状态代码 404
如果尝试停用组织所有者，则会返回 HTTP 状态代码 400

PATCH /Users/<id>

此端点用于对我们系统中的用户详细信息进行部分更新，这意味着您只能使用此端点来更改用户的某些属性。与之相比，PUT 可替换整个用户。

它可以包含活跃属性，这将会导致停用或重新激活用户。

每个请求的正文必须包含 URI 值为“urn:ietf:params:scim:api:messages:2.0:PatchOp”的“架构”属性。
HTTP PATCH 请求的正文必须包含“操作”属性，其值为一个或多个 PATCH 操作的数组。每个 PATCH 操作对象必须恰好有一个“op”成员，其值指示要执行的操作，并且可以是“添加”、“移除”或“替换”中的一个。
“路径”属性可以为空，在这种情况下，“值”应当为采用 {“path”: “value”} 格式的字典。

响应：

HTTP 状态代码 200 和更新的成功用户资源
如果未找到用户，则会返回 HTTP 状态代码 404
如果尝试停用组织所有者或操作无效，则会返回 HTTP 状态代码 400

群组端点

支持的属性

SCIM 属性	是否必填？	说明
显示名称	是	群组标题。在所有 Udemy Business 群组中必须唯一。
外部 ID	否	身份提供程序中的群组外部 ID

请注意：如果您指定不在此列表中的任何其他属性，系统将忽略该属性。

GET /Groups

此端点用于获取所有已配置群组的分页列表。包括对结果进行分页的 startIndex 和 count 查询字符串参数。

请记住，只会返回使用 SCIM 创建的群组。不会返回在 Udemy Business 中创建的群组。

GET /Groups?filter=

此端点用于按特定属性筛选群组。例如，可以根据显示名称属性进行搜索：

GET /Groups?filter=displayName eq "Marketing”

此时将返回群组资源列表。如果没有任何结果，将返回一个空列表。

请注意：您需要对参数进行 URL 编码，因此请求会变为：
GET /Groups?filter=displayName%20eq%20%22Marketing%22

支持的筛选条件如下：

显示名称
外部 ID
Id
member.value

支持的运算符如下：

响应：

HTTP 状态代码 200 和成功的实体列表
如果使用了不受支持的筛选条件，则会返回 HTTP 状态代码 501

POST /Groups

此端点用于在 Udemy Business 中创建（配置）新群组。

响应：

HTTP 状态代码 409。如果组织中已存在相同名称的已配置群组，我们将返回 409（冲突）和唯一的 scimType 错误代码。
成功创建群组后，我们将返回该群组的完整表示形式，HTTP 状态代码 201（已创建）以及包含创建群组资源 URL 的 Location 标头。

GET /Groups/<id>

此端点用于从 Udemy Business 中提取群组详细信息。

响应：

HTTP 状态代码 200 和群组资源
如果未找到群组，则会返回 HTTP 状态代码 404

PUT /Groups/<id>

此端点用于替换 Udemy Business 中的群组详细信息。

响应：

HTTP 状态代码 200 和更新的群组资源
如果群组不存在，则会返回 HTTP 状态代码 404

PATCH /Groups/<id>

此端点用于对 Udemy Business 中的群组详细信息进行部分更新。

PATCH 端点比其他端点更难以处理，因为它支持不同类型的操作（及其组合）：

替换操作可更改指定值。在我们的示例中为群组名称或成员。
移除操作可从群组中移除成员。
添加操作可向群组添加成员。

规则如下：

我们永远不会从群组中移除未配置的成员（例如，在“替换”成员操作时）。
无论操作次数多少，系统都将 PATCH 请求视为原子操作。

输入验证如下：

每个请求的正文必须包含 URI 值为“urn:ietf:params:scim:api:messages:2.0:PatchOp”的“架构”属性。
HTTP PATCH 请求的正文必须包含“操作”属性，其值为一个或多个 PATCH 操作的数组。每个 PATCH 操作对象必须恰好有一个“op”成员，其值指示要执行的操作，并且可以是“添加”、“移除”或“替换”中的一个。
“路径”属性可以为空，在这种情况下，“值”应当为采用 {“path”: “value”} 格式的字典。
对于“移除”操作，需要“成员”路径。
对于“添加”操作，应当存在“成员”或“外部 ID” “路径”。
对于“替换”操作，可能存在“成员”路径。如果不存在，则意味着我们正在替换群组详细信息（如群组名称）而不是成员。

请注意：

向群组分配/取消分配用户是异步操作，因此不会在 Udemy Business 中立即反映这些更改。
我们不支持嵌套群组，因此在此请求期间将会忽略这些群组。

响应：

如果操作成功，则会返回 HTTP 状态代码 204
如果群组不存在，则会返回 HTTP 状态代码 404
如果尝试向非组织成员用户分配群组，则会返回 HTTP 状态代码 404 和错误详细信息
如果请求未通过验证，则会返回 HTTP 状态代码 400，响应正文中会显示错误详细信息

DELETE /Groups/<id>

此端点用于移除或取消配置 Udemy Business 中的群组。

规则如下：

如果群组中包含未配置的成员，则会从群组中移除已配置的用户，删除“OrganizationSCIMGroup”记录。

响应：

如果操作成功，则会返回 HTTP 状态代码 204
如果群组不存在，则会返回 HTTP 状态代码 404

概述

SCIM 协议说明

如何访问 API？

SCIM API 端点

用户端点

GET /Groups/<id>

延伸阅读

需要帮助？

概述

SCIM 协议说明

如何访问 API？

SCIM API 端点

用户端点

GET /Groups/<id>

延伸阅读

相关文章

需要帮助？