SCIM 预配应用程序接口
- 阅读
- 2 分钟
- 类别
- Proton VPN for Business
概览
SCIM（跨域身份管理系统）预配应用程序接口是一种标准协议，用于在基于云的应用中自动执行用户身份的预配和管理。Proton 支持此 API，允许您创建、更新、删除和管理用户帐户与群组。该 API 基于 SCIM 2.0 规范，提供通用用户架构和 RESTful API 接口，便于集成。
Proton 支持以下身份提供商：
- Okta (https://www.okta.com/（新窗口）)
- Microsoft Entra ID
来自身份提供商的全部调用的基础网址为：https://scim.proton.me/{tenantId}/v2/（新窗口）。全部 SCIM 方法都是此基础网址的分支。
身份验证
调用任何 SCIM 方法时，令牌必须包含在类型为 Bearer 的 Authorization 标题中。此令牌可在单点登录 > SCIM 自动预配部分中生成和更换。点击“生成新令牌”按钮并复制已生成的令牌。
例如：
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
用户
核心属性
| id | 由 Proton 定义的 SCIM 资源（如用户）的唯一标识符。 |
| userName（必填） | 用户的唯一标识符。此处我们使用电子邮件作为 userName。 |
| active | 布尔值，指示该用户是否已启用。默认值为 true。 |
操作
检索所有用户的分页列表
请求
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
响应
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 1,
"itemsPerPage": 1,
"startIndex": 1,
"Resources": [
{
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true
}
]
}已复制
创建新用户
请求
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
响应
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-25T04:39:27Z",
"lastModified": "2024-07-25T04:39:27Z",
"location": "https://scim.proton.me/{tenent-id}/v2/Users/avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
}
}
已复制
检索单个用户
请求
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
响应
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==",
"userName": "test@sso.protonhub.org",
"active": true,
"meta": {
"resourceType": "User",
"created": "2024-07-24T06:22:20Z",
"lastModified": "2024-07-24T06:22:20Z",
"location": "https://scim.proton.me/{tenentId}/v2/Users/avveKyJZ_cCkUL1iBZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
"version": "1"
},
"externalId": "00uganxwluxxxxxxxxxx"
}已复制
删除用户
请求
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
群组
核心属性
| id | 由 Proton 定义的 SCIM 资源（如用户）的唯一标识符。 |
| displayName | 群组名称。 |
| members | 群组成员列表。 |
操作
获取群组列表
请求
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
响应
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 0,
"itemsPerPage": 100,
"startIndex": 1,
"Resources": [
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [
{
"value": "2819c223-7f76-453a-919d-413861904646",
"display": "John Doe"
}
],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
]
}已复制
通过唯一 ID 检索群组的详细信息
请求
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}已复制
响应
{
"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
"displayName": "Admins",
"members": [{ "value": "2819c223-7f76-453a-919d-xxxxxxxxxxxx", "display": "John Doe" }],
"meta": {
"resourceType": "Group",
"created": "2024-07-25T05:10:22Z",
"lastModified": "2024-07-25T05:10:22Z",
"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
}
}
已复制
错误处理
响应采用 RFC-7644 第 3.12 节（新窗口）规定的格式，并附有指示错误性质的 HTTP 状态代码，以及提供更多详细信息的响应正文。
错误响应
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
已复制
最常见的错误
- 400 Bad Request：请求无效或无法以其他方式提供服务。
- 404 Not Found：找不到所请求的资源。
- 409 Conflict：由于与目标资源的当前状态存在冲突，无法完成请求。
uniqueness：系统中已存在该唯一属性值。
- 500 Internal Server Error：服务器端发生错误。