SCIM doelsysteem documentatie
AlgemeenÂ
System for Cross-domain Identity Management (SCIM) is een open standaard voor het uitwisselen van identiteitsgegevens tussen IT-systemen via RESTful webservices.  Â
WebIDM implementeert
Dit document dient enkel ter verduidelijking van de SCIM implementatie door WebIDM. Het gedrag van de web service wordt uitgebreid beschreven in RFC 7644.Â
Aandachtspunten bij de SCIM implementatie van WebIDM:Â Â
Er wordt geen gebruik gemaakt van het PATCH verb om resources te wijzigen, enkel PUT wordt gebruikt waarmee de resource volledig wordt vervangen door de nieuwe waarde.Â
Enkel het User schema werd geïmplementeerd. Er wordt geen gebruik gemaakt van het Group schema. Meer informatie: RFC 7642.
WebIDM is in de context van bovenstaande RFC de Enterprise Cloud Subscriber (ECS). Â
De applicatie die informatie ontvangt van WebIDM neemt hier de rol van Cloud Service Provider (CSP) op, verder Service Provider genoemd.Â
Business procesÂ
Aanmaak van een gebruikerÂ
Een gebruiker wordt aangemaakt wanneer deze minstens één werkrelatie heeft met een toegekend recht in WEBIDM.
Volgende informatie wordt minstens doorgegeven:Â
Categorie | WebIDM attribuut | Beschrijving | Verplicht | SCIM property |
Medewerker info    | VO-id/ VirtualIdentity UUID | Unieke id binnen een doelgroep (GID, Economische actoren, Lokale Besturen, Onderwijs) |  | externalId |
Voornaam |  |  | name.givenName | |
Achternaam |  |  | name.familyName | |
Status |  |  | active | |
Link medewerker – organisatie info (werkrelatie)  | Organisatiecode   | Unieke sleutel van de organisatie (zoals OVO, KBO nummer,…). Wordt toegevoegd aan e-mailadressen, rechten of contexten. *Verplicht wanneer e-mailadres, recht of context geprovisioneerd wordt. | * | |
Gebruikersrechten | Het recht voor een bepaalde organisatie (werkrelatie). Formaat: Fully Qualified of Simple Fully Qualified: [Organisatiecode]-[Categorie key]:[Categorie waarde],[Account type key:Account type waarde,…]-[Recht]Â
Simple: [Recht] Opgelet: dit formaat is onnauwkeurig en verliest cruciale informatie. Dit formaat kan enkel gebruikt worden indien de werkrelatie-informatie niet relevant is. AgO_VlimpersLeren_GID_CompEnt_Gebruiker |  | entitlements (lijst) |
Volgende informatie kan optioneel worden doorgegeven:Â
Categorie | WebIMD attribuut | Beschrijving | Verplicht | SCIM property |
Medewerker info | Login | Unieke gegenereerde gebruikersnaam Heeft geen vast formaat lastnafi (met als formaat 6 letters lastname + 2 letters firstname) | userName | |
INSZ-nummer | Rijksregister- of BISnummer | urn:ietf:params:scim:schemas:extension:idm:2.0:User.socialSecurityNumber | ||
Doelgroepcode | De code van de doelgroep waar de gebruiker en zijn werkrelatie onder zijn aangemaakt. | urn:ietf:params:scim:schemas:extension:idm:2.0:User.closedUserGroupCode en/of urn:ietf:params:scim:schemas:extension:idm:2.0:Cug.code | ||
Doelgroepnaam | De naam van de doelgroep waar de gebruiker en zijn werkrelatie onder zijn aangemaakt. | urn:ietf:params:scim:schemas:extension:idm:2.0:Cug.name | ||
Link medewerker – organisatie info (werkrelatie) | E-mailadressen | Het e-mailadres wordt opgeslagen op niveau van de werkrelatie, maar is niet noodzakelijk verschillend per werkrelatie. Â
{
  "value": "webidm@vlaanderen.be",
  "type": "OVO000089"
} | emails (lijst)Â | |
Telefoonnummers | Is niet noodzakelijk verschillend per werkrelatie. Wordt samen met organisatiecode opgeslagen waardoor de link werkrelatie-telefoonnummer gemaakt wordt. {
  "value": "+32000000",
  "type": "OVO000089"
} | phoneNumbers (lijst)Â | ||
Contexten | De context (zoals Rol, Maatregel, Domein,..) binnen een bepaald recht. Formaat: Fully Qualified Fully Qualified: [Organisatiecode]-[Categorie key]:[Categorie waarde],[Account type key:Account type waarde,…]-[Recht]:[Contextwaarde]Â
| roles (lijst)Â | ||
Contexten | De context (zoals Rol, Maatregel, Domein,...) binnen een bepaald recht. Formaat: Fully Qualified of Simple Fully Qualified: [Organisatiecode]-[Categorie key]:[Categorie waarde],[Account type key:Account type waarde,…]-[Recht]:[Contextwaarde]Â
Simple:Â [Contextwaarde]Â Opgelet:Â dit formaat is onnauwkeurig en verliest cruciale informatie. Dit formaat kan enkel gebruikt worden indien de werkrelatie - of recht informatie niet belangrijk is. | groups (lijst)Â |
Wijzigen van een gebruikerÂ
Een update actie wordt uitgevoerd:Â
Als de gebruiker een nieuwe actieve toekenning van het recht krijgt onder een werkrelatie.
Actief wilt hier zeggen:
De start tijd van de werkrelatie is kleiner dan of gelijk aan vandaag.
De eind tijd van de werkrelatie is groter dan of gelijk aan vandaag.
De start tijd van de toekenning van het recht is kleiner dan of gelijk aan vandaag.
De eind tijd van de toekenning van het recht is groter dan of gelijk aan vandaag.
De werkrelatie is actief, niet gepauzeerd.
De toekenning van het recht is actief, niet gepauzeerd.Als de gegevens van een actieve toekenning van het recht wijzigt.
Vb: Context (rol) wordt toegevoegd, verwijderd of aangepastAls een actieve toekenning van het recht verwijderd wordt.
Als de eind tijd van de toekenning van het recht kleiner is dan vandaag. Ofwel: de actieve toekenning van het recht verloopt.
Als de informatie van de gebruiker of van een bestaande werkrelatie (met actieve toekenning van het recht) wijzigt.Â
Vb: nieuw emailadres, nieuwe login, naamswijziging,…​ÂAls de toekenning van het recht gepauzeerd wordt.
Als de werkrelatie met actieve toekenning van het recht gepauzeerd wordt.
Verwijderen van een gebruikerÂ
Een delete actie wordt uitgevoerd:Â
Als de gebruiker zijn laatste actieve toekenning van het recht verliest.
De Service Provider moet gebruikers op zijn minst inactief maken bij een delete en alle gekende rechten verwijderen.Â
PauzerenÂ
WebIDM heeft een pauzeer-knop op niveau van de werkrelatie en recht. Dit laat de lokale beheerder toe om delen van een gebruiker tijdelijk te inactiveren, bv bij langdurige ziekte.​Â
Pauzeren zal lijken op toekenningen die verdwijnen in WebIDM:Â
Updates met daarin minder werkrelaties of rechten dan de Service Provider op dat moment kent.Â
Actief/niet-actief vlagÂ
Op niveau van een gebruiker bestaat een vlag die enkel systeembeheerders kunnen aan- of uitzetten om gebruikers in uitzonderlijke gevallen dringend te deactiveren zonder deze helemaal te moeten verwijderen.Â
Het pauzeren van een volledige gebruiker zal een update uitvoeren met de SCIM active property op false.Â
Ook bij de Service Provider moeten a.d.h.v. deze vlag gebruikers ge-activeerd of gedeactiveerd worden.Â
Dit zijn update acties, geen delete acties.Â
Technisch implementatieÂ
SCIM EndpointÂ
De targetapplicatie waar WebIDM naar provisioneert, moet minstens volgende functionaliteit in zijn SCIM endpoints implementeren:Â
Find User
Create User
Update User
Delete User
OpenAPI specificatie
Deze kan bekeken worden op https://editor.swagger.io/
Find UserÂ
GETÂ v2/Users?filter=externalId Eq "{externalId}" | ||
---|---|---|
externalId | 4ad4896c-2f09-4906-ba25-32d5543bd71b | |
Responses | ||
Code | Description | Example |
200 | OK | |
200 | OK |
Create UserÂ
Het aanmaken van de User gebeurt d.m.v. een POST request om de User aan te maken. Deze POST bevat naast persoonsgegevens ook de rechten en indien geconfigureerd optionele attributen als e-mailadressen of rollen.Â
POSTÂ v2/Users | ||
---|---|---|
Body | ||
Responses | ||
Code | Description | Example |
201 | Created | De body bevat een volledige weergave van de aangemaakte resource. |
409 | Conflict | Als de service provider vaststelt dat de creatie van de User conflicteert met een bestaande User moet er een status 409 teruggegeven worden met een "scimType" error code van "uniqueness", as per Section 3.12. |
Update UserÂ
PUTÂ v2/Users/{id} | ||
---|---|---|
id | e65adc36-cb15-4b4d-b8df-cb6cba347f8c | |
Body | ||
Responses | ||
Code | Description | Example |
200 | OK | De body bevat een volledige weergave van de resource. |
Delete UserÂ
DELETEÂ v2/Users/{id} | ||
---|---|---|
id | e65adc36-cb15-4b4d-b8df-cb6cba347f8c | |
Responses | ||
Code | Description | Example |
204 | No content | De Service Provider zet de User minstens op inactief als er voor gekozen wordt om de resource niet definitief te verwijderen. |
404 | Not found | User was voorheen deleted/op inactief gezet. |
Health checkÂ
Een health check service moet geïmplementeerd worden door de Service Provider. WebIDM beslist aan de hand van de respons of er een provisionering kan gestart worden. Â
GETÂ https://[yourScimEndpoint]/statuscheck | ||
---|---|---|
Responses | ||
Code | Description | Result |
200 | OK | provisionering kan starten |
4xx | provisionering on hold, er worden door WebIDM geen gegevens uitgeleverd aan de Service Provider |
BeveiligingÂ
Voor het beveiligen van de communicatie tussen WebIDM en de SCIM Service Provider ondersteunen we enkel MutualTLS (mTLS)Â authenticatie.Â
Naast deze beveiligingsmaatregelen, moeten mogelijks ook de nodige datastromen voorzien worden tussen WebIDM en de Service Provider. Â
MutualTLS
Voor een veilige verbinding, zowel over het lokaal netwerk binnen VO als over het internet, moeten WebIDM en de SCIM Service Provider MutualTLS authenticatie implementeren, waarbij beide partijen zich authenticeren tegenover elkaar d.m.v. X509 certificaten.Â
De SCIM Service Provider moet het client certificaat van WebIDM vertrouwen. Daarnaast moet de SCIM Service Provider een GlobalSign of VO PKI SSL server certificaat voorzien dat WebIDM kan vertrouwen.Â
Verschillen tegenover vorige versie
WebIDM houdt de ID die wordt gecreëerd door de Service Provider bij. De Service Provider ondersteunt de Find User by externalId. Als WebIDM en de Service Provicer out of sync geraken wordt de Find User gebruikt om de Service Provider ID op te halen.
WebIDM doet enkel calls naar de Service Provider indien er wijzigingen zijn. In de vorige versie kon het gebeuren dat er calls gemaakt werden naar de Service Provider ook al was er voor die specifieke User resource niets gewijzigd, maar wel in andere rechten van die Gebruiker.
Het aanmaken van een gebruiker gebeurt aan de hand van één enkele Create User call. In de vorige versie was dit 1 Create User call gevolgd door 1 of meedere Update User calls.
De SCIM User property Groups wordt ondersteund. De waarde hiervan kan Fully Qualified of Simple zijn.
Â
Op deze pagina:Â
- 1 AlgemeenÂ
- 2 Business procesÂ
- 3 Technisch implementatieÂ
- 3.1 SCIM EndpointÂ
- 3.2 OpenAPI specificatie
- 3.3 Find UserÂ
- 4 Create UserÂ
- 4.1 Update UserÂ
- 4.2 Delete UserÂ
- 4.3 Health checkÂ
- 5 BeveiligingÂ
- 5.1 MutualTLS
- 6 Verschillen tegenover vorige versie
Vragen of suggesties, contacteer ons via: integraties@vlaanderen.beÂ
Heb je nood aan ondersteuning bij het gebruik van de toepassing, contacteer de 1700.