API provisi SCIM
- Membaca
- 4 mnt
- Kategori
- Proton VPN for Business
Ikhtisar
API Provisi SCIM (System for Cross-domain Identity Management) adalah protokol standar untuk mengotomatiskan provisi dan pengelolaan identitas pengguna di aplikasi berbasis cloud. Proton mendukung API ini, yang memungkinkan untuk membuat, memperbarui, menghapus, dan mengelola akun serta grup pengguna. API ini didasarkan pada spesifikasi SCIM 2.0, yang menyediakan skema pengguna umum dan antarmuka RESTful API untuk kemudahan integrasi.
Proton mendukung penyedia identitas berikut:
- Okta (https://www.okta.com/(jendela baru))
- Microsoft Entra ID
URL dasar untuk semua panggilan dari penyedia identitas adalah: https://scim.proton.me/{tenantId}/v2/(jendela baru). Semua metode SCIM merupakan cabang dari URL dasar ini.
Autentikasi
Token harus disertakan dalam header Authorization dengan tipe Bearer saat memanggil salah satu metode SCIM. Token ini dapat dihasilkan dan diganti di bagian Single-sign-on > provisi otomatis SCIM. Klik tombol “Hasilkan token baru” dan salin token yang dihasilkan.
Sebagai contoh:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Pengguna
Atribut Inti
| id | Pengidentifikasi unik untuk sumber daya SCIM, seperti pengguna, yang ditentukan oleh Proton. |
| userName (wajib) | Pengidentifikasi unik untuk pengguna. Di sini email digunakan sebagai userName. |
| aktif | Boolean yang menunjukkan apakah pengguna aktif. Nilai bawaannya adalah true. |
Operasi
Mengambil daftar berhalaman dari seluruh pengguna
Permintaan
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respons
{
"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
}
]
}Membuat pengguna baru
Permintaan
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respons
{
"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"
}
}
Mengambil satu pengguna
Permintaan
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respons
{
"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"
}Menghapus pengguna
Permintaan
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Grup
Atribut Inti
| id | Pengidentifikasi unik untuk sumber daya SCIM, seperti pengguna, yang ditentukan oleh Proton. |
| displayName | Nama untuk grup. |
| members | Daftar anggota grup. |
Operasi
Mendapatkan daftar grup
Permintaan
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respons
{
"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"
}
}
]
}Mengambil rincian grup berdasarkan ID uniknya
Permintaan
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Respons
{
"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"
}
}
Penanganan Kesalahan
Respons diformat mengikuti RFC-7644 pasal 3.12(jendela baru) yang dikirimkan dengan kode status HTTP yang menunjukkan sifat kesalahan dan isi respons yang memberikan rincian lebih lanjut.
Respons Kesalahan
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Kesalahan yang paling umum
- 400 Bad Request: Permintaan tidak valid atau tidak dapat dilayani.
- 404 Not Found: Sumber daya yang diminta tidak dapat ditemukan.
- 409 Conflict: Permintaan tidak dapat diselesaikan karena adanya konflik dengan keadaan saat ini dari sumber daya target.
uniqueness: Nilai atribut unik sudah ada di dalam sistem.
- 500 Internal Server Error: Terjadi kesalahan pada sisi server.