SCIM 佈建應用程式介面
- 閱讀
- 2 分鐘
- 類別
- Proton VPN for Business
概觀
SCIM（System for Cross-domain Identity Management，跨網域身分管理系統）佈建應用程式介面是用於在雲端應用程式中自動佈建和管理使用者身分的標準協定。Proton 支援此應用程式介面，其允許您建立、更新、刪除和管理使用者帳號與群組。此應用程式介面以 SCIM 2.0 規格為基礎，提供通用的使用者架構和 RESTful 應用程式介面，以便於整合。
Proton 支援以下身分提供者：
- Okta (https://www.okta.com/(新視窗))
- Microsoft Entra ID
來自身分提供者的所有呼叫之基礎網址 為： https://scim.proton.me/{tenentId}/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：伺服器端發生錯誤。