SCIM-provisioinnin API
- Luetaan
- 4 min
- Kategoria
- Proton VPN for Business
Yleiskatsaus
SCIM (System for Cross-domain Identity Management) -provisiointi-API on standardiprotokolla käyttäjäidentiteettien automaattiseen provisiointiin ja hallintaan pilvipohjaisissa sovelluksissa. Proton tukee tätä API-rajapintaa, jonka avulla voitte luoda, päivittää, poistaa ja hallita käyttäjätilejä sekä ryhmiä. API perustuu SCIM 2.0 -määritykseen, joka tarjoaa yhteisen käyttäjäskeeman ja RESTful API -rajapinnan integraation helpottamiseksi.
Proton tukee seuraavia identiteetintarjoajia:
- Okta (https://www.okta.com/(uusi ikkuna))
- Microsoft Entra ID
Perus-URL kaikille identiteetintarjoajalta tuleville kutsuille on: https://scim.proton.me/{tenentId}/v2/(uusi ikkuna). Kaikki SCIM-metodit ovat tämän perus-URL-osoitteen alahaaroja.
Tunnistautuminen
Tunniste on sisällytettävä Authorization-otsakkeeseen tyypillä Bearer, kun kutsutaan mitä tahansa SCIM-metodeista. Tämä tunniste voidaan luoda ja korvata kohdassa Kertakirjautuminen (Single-sign-on) > Automaattinen SCIM-provisiointi. Klikatkaa “Luo uusi tunniste” -painiketta ja kopioikaa luotu tunniste.
Esimerkiksi:
GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Käyttäjät
Ydinmääritteet
| id | Protonin määrittämä yksilöllinen tunniste SCIM-resurssille, kuten käyttäjälle. |
| userName (vaaditaan) | Käyttäjän yksilöllinen tunniste. Tässä käytämme sähköpostiosoitetta userName-arvona. |
| active | Boolean-arvo, joka osoittaa, onko käyttäjä aktiivinen. Oletusarvo on true. |
Toiminnot
Hae sivutettu luettelo kaikista käyttäjistä
Pyyntö
GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Vastaus
{
"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
}
]
}Luo uusi käyttäjä
Pyyntö
POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Vastaus
{
"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"
}
}
Hae yksittäinen käyttäjä
Pyyntö
GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Vastaus
{
"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"
}Poista käyttäjä
Pyyntö
DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Ryhmät
Ydinmääritteet
| id | Protonin määrittämä yksilöllinen tunniste SCIM-resurssille, kuten käyttäjälle. |
| displayName | Ryhmän nimi. |
| members | Luettelo ryhmän jäsenistä. |
Toiminnot
Hae luettelo ryhmistä
Pyyntö
GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Vastaus
{
"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"
}
}
]
}Hae ryhmän tiedot sen yksilöllisen tunnuksen (ID) perusteella
Pyyntö
GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}Vastaus
{
"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"
}
}
Virheiden käsittely
Vastaukset on muotoiltu standardin RFC-7644 osion 3.12(uusi ikkuna) mukaisesti, ja ne toimitetaan HTTP-tilakoodilla, joka ilmaisee virheen luonteen, sekä vastauksen rungolla, joka sisältää lisätietoja.
Virhevastaus
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"detail": "UserName is already taken",
"status": "400"
}
Yleisimmät virheet
- 400 Bad Request: Pyyntö oli virheellinen tai sitä ei voida muuten käsitellä.
- 404 Not Found: Pyydettyä resurssia ei löytynyt.
- 409 Conflict: Pyyntöä ei voitu suorittaa loppuun kohderesurssin nykyisen tilan kanssa ilmenneen ristiriidan vuoksi.
uniqueness: Yksilöllinen määritteen arvo on jo olemassa järjestelmässä.
- 500 Internal Server Error: Palvelinpuolella tapahtui virhe.