API cấp phát SCIM
- Đọc
- 6 phút
- Danh mục
- Proton VPN for Business
Tổng quan
API Cấp phát SCIM (Hệ thống Quản lý Danh tính Liên miền) là một giao thức chuẩn để tự động hóa việc cấp phát và quản lý danh tính người dùng trong các ứng dụng dựa trên đám mây. Proton hỗ trợ API này, cho phép tạo, cập nhật, xóa và quản lý các tài khoản người dùng và các nhóm. API dựa trên đặc tả SCIM 2.0, cung cấp lược đồ người dùng chung và giao diện API RESTful để dễ dàng tích hợp.
Proton hỗ trợ các nhà cung cấp danh tính sau:
- Okta (https://www.okta.com/(cửa sổ mới))
- Microsoft Entra ID
URL cơ sở cho tất cả cuộc gọi từ nhà cung cấp danh tính là: https://scim.proton.me/{tenantId}/v2/(cửa sổ mới). Tất cả các phương thức SCIM đều là nhánh của URL cơ sở này.
Xác thực
Mã thông báo phải được bao gồm trong tiêu đề Authorization với Loại là Bearer khi gọi bất kỳ phương thức SCIM nào. Mã thông báo này có thể được tạo và thay thế trong phần Single-sign-on > SCIM automatic provisioning. Nhấp vào nút “Tạo mã thông báo” và Sao chép mã thông báo đã tạo.
Ví dụ:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Người dùng
Các thuộc tính cốt lõi
| id | Một định danh duy nhất cho tài nguyên SCIM, chẳng hạn như Người dùng, được xác định bởi Proton. |
| userName (bắt buộc) | Một định danh duy nhất cho người dùng. Ở đây chúng tôi sử dụng email làm Tên người dùng. |
| active | Một giá trị boolean cho biết người dùng có Hoạt động hay không. Giá trị mặc định là true. |
Các thao tác
Truy xuất danh sách tất cả Người dùng được phân trang
Yêu cầu
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Phản hồi
{
"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
}
]
}Đã sao chép
Tạo người dùng mới
Yêu cầu
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Phản hồi
{
"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"
}
}
Đã sao chép
Truy xuất một Người dùng đơn lẻ
Yêu cầu
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Phản hồi
{
"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"
}Đã sao chép
Xóa một người dùng
Yêu cầu
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Các nhóm
Các thuộc tính cốt lõi
| id | Một định danh duy nhất cho tài nguyên SCIM, chẳng hạn như Người dùng, được xác định bởi Proton. |
| displayName | Tên cho nhóm. |
| thành viên | Danh sách các thành viên của nhóm. |
Các thao tác
Lấy danh sách các nhóm
Yêu cầu
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Phản hồi
{
"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"
}
}
]
}Đã sao chép
Truy xuất chi tiết của một nhóm theo ID duy nhất của nhóm đó
Yêu cầu
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Đã sao chép
Phản hồi
{
"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"
}
}
Đã sao chép
Xử lý lỗi
Các phản hồi được định dạng theo RFC-7644 mục 3.12(cửa sổ mới) được gửi kèm với mã Trạng thái HTTP cho biết bản chất của lỗi và nội dung phản hồi cung cấp chi tiết.
Phản hồi lỗi
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Đã sao chép
Các lỗi phổ biến nhất
- 400 Bad Request: Yêu cầu không hợp lệ hoặc không thể được phục vụ.
- 404 Not Found: Tài nguyên được yêu cầu không thể tìm thấy.
- 409 Conflict: Không thể hoàn tất yêu cầu do xung đột với trạng thái hiện tại của tài nguyên đích.
uniqueness: Một Giá trị thuộc tính duy nhất đã tồn tại trong hệ thống.
- 500 Internal Server Error: Đã xảy ra lỗi ở phía máy chủ.