Interfejs API do aprowizacji SCIM
- Odczytywanie
- 4 min
- Kategoria
- Proton VPN for Business
Przegląd
Interfejs API do aprowizacji SCIM (System for Cross-domain Identity Management) to standardowy protokół automatyzacji aprowizacji tożsamości użytkowników i zarządzania nimi w aplikacjach chmurowych. Proton obsługuje ten interfejs API, co pozwala Ci tworzyć, aktualizować, usuwać konta użytkowników i grupy oraz nimi zarządzać. Ten interfejs API bazuje na specyfikacji SCIM 2.0, która zapewnia wspólny schemat użytkownika i interfejs RESTful API w celu ułatwienia integracji.
Proton obsługuje następujących dostawców tożsamości:
- Okta (https://www.okta.com/(nowe okno))
- Microsoft Entra ID
Bazowy adres URL dla wszystkich wywołań od dostawcy tożsamości to: https://scim.proton.me/{tenentId}/v2/(nowe okno). Wszystkie metody SCIM są gałęziami tego bazowego adresu URL.
Uwierzytelnianie
Token musi być zawarty w nagłówku Authorization o typie Bearer przy wywoływaniu dowolnej metody SCIM. Token ten możesz wygenerować i zastąpić w sekcji Jednokrotne logowanie > Automatyczna aprowizacja SCIM. Kliknij przycisk “Generuj nowy token” i skopiuj wygenerowany token.
Na przykład:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Użytkownicy
Atrybuty podstawowe
| id | Unikalny identyfikator zasobu SCIM, takiego jak użytkownik, zdefiniowany przez Proton. |
| userName (wymagane) | Unikalny identyfikator użytkownika. W tym przypadku jako userName używamy adresu e-mail. |
| active | Wartość logiczna (boolean) wskazująca, czy użytkownik jest aktywny. Domyślna wartość to true. |
Operacje
Pobieranie stronicowanej listy wszystkich użytkowników
Żądanie
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Odpowiedź
{
"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
}
]
}Tworzenie nowego użytkownika
Żądanie
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Odpowiedź
{
"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"
}
}
Pobieranie pojedynczego użytkownika
Żądanie
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Odpowiedź
{
"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"
}Usuwanie użytkownika
Żądanie
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Grupy
Atrybuty podstawowe
| id | Unikalny identyfikator zasobu SCIM, takiego jak użytkownik, zdefiniowany przez Proton. |
| displayName | Nazwa grupy. |
| members | Lista członków grupy. |
Operacje
Pobieranie listy grup
Żądanie
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Odpowiedź
{
"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"
}
}
]
}Pobieranie szczegółów grupy na podstawie jej unikalnego identyfikatora ID
Żądanie
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Odpowiedź
{
"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"
}
}
Obsługa błędów
Odpowiedzi są sformatowane zgodnie z sekcją 3.12 specyfikacji RFC-7644(nowe okno) i są dostarczane z kodem statusu HTTP wskazującym na charakter błędu oraz treścią odpowiedzi zawierającą więcej szczegółów.
Odpowiedź o błędzie
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Najczęstsze błędy
- 400 Bad Request: Żądanie było nieprawidłowe lub nie może zostać obsłużone z innych przyczyn.
- 404 Not Found: Nie można odnaleźć żądanego zasobu.
- 409 Conflict: Żądanie nie mogło zostać zrealizowane z powodu konfliktu z obecnym stanem docelowego zasobu.
uniqueness: Unikalna wartość atrybutu już istnieje w systemie.
- 500 Internal Server Error: Wystąpił błąd po stronie serwera.