Als u in uw applicatie de ECK iD's, die in Magister aan leerlingen/studenten en personeel gekoppeld worden nodig heeft, dan kunt u die op drie manieren uit Magister ontvangen:
- Via de SSO inlog met Kennisnet (mits de school Magister als IdP voor Kennisnet ingesteld heeft)
- Via UWLR (u kunt contact opnemen via deze pagina voor meer informatie)
- Door een SCIM service provider te leveren volgens deze specificatie.
In deze specificatie leest u waar uw implementatie aan moet voldoen om te koppelen met Magister en welke gegevens de school van u nodig heeft om een koppeling te kunnen leggen.
Hier moet uw implementatie aan voldoen:
- SCIM
- Flow Magister implementatie
- Randvoorwaarden aan de SCIM-implementatie
- Foutmeldingen in Magister relateren aan uw eigen logging
- Gegevens die de school nodig heeft
SCIM
SCIM staat voor "System for Cross-domain Identity Management" en is een internationale standaard voor het uitwisselen van identiteitsgebonden informatie.
EduUser
In de educatieve content keten wordt de resource 'EduUser' gebruikt. Deze valt als volgt in de structuur zoals die gedefinieerd is in SCIM:
EduUser valt niet onder User, omdat dan verplichte attributen zoals 'accountname' opgenomen moeten worden die in de content keten niet noodzakelijk of gewenst zijn. Vanuit het oogpunt van privacy, door data minimalisation, is dat niet wenselijk.
Attributen
Voor het uitwisselen van ECK iD's gebruikt Magister de 'EduUser'- resource. Deze bevat de volgende attributen:
- id
- EduUser: externalId
- EduUser: eckId
- EduUser:name: familyName
- EduUser:name: givenName
Volgens de SCIM RFC moet elke resource een attribuut 'Id' hebben. Dit wordt toegekend door de resource provider.
De 'externalId' wordt momenteel gevuld met de 'nlEduPersonRealId' (zoals Magister deze genereert wanneer Magister IdP voor Kennisnet is). Voor de ondersteuning van het verwijderen van ECK iD's is het vereist dat het create/update endpoint het gebruikers-id teruggeeft in het response.
Attributen zonder waarde worden door Magister niet verzonden en worden ook niet verwacht in het antwoord van een SCIM service provider.
Schema EduUser resource
!Let op: het schema is breder dan de kolomweergave.
[
{
"id":"urn:ietf:params:scim:schemas:extension:nleducation:1.0:eduuser",
"name":"eduUser",
"description":"SCIM extended resource for representing users for digital educational content in the Netherlands",
"attributes":[
{
"name":"id",
"type":"string",
"multiValued":false,
"description":"Unique identifier for the SCIM Resource as defined by the Service Provider",
"schema":"urn:scim:schemas:core:1.0",
"readOnly":true,
"required":true,
"caseExact":false,
"returned":"always",
"uniqueness":"server"
},
{
"name":"externalId",
"type":"string",
"multiValued":false,
"description":"The identification of the user as defined by Kennisnet: nlEduPersonRealId",
"mutability":"immutable",
"required":true,
"caseExact":false,
"returned":"always",
"uniqueness":"global"
},
{
"name":"eckId",
"type":"string",
"multiValued":false,
"description":"The unique identification of the user for digital content",
"mutability":"immutable",
"required":true,
"caseExact":false,
"returned":"request",
"uniqueness":"global"
},
{
"name":"name",
"type":"complex",
"multiValued":false,
"description":"A complex type containing the name of the EduUser",
"mutability":"readWrite",
"required":true,
"caseExact":false,
"uniqueness":"none",
"subAttributes":[
{
"name":"familyName",
"type":"string",
"multiValued":false,
"description":"The surname of the EduUser, including prefixes like 'van' or 'van der'",
"mutability":"readWrite",
"required":true,
"returned":"always",
"caseExact":false
},
{
"name":"givenName",
"type":"string",
"multiValued":false,
"description":"The given name of the EduUser",
"mutability":"readWrite",
"required":false,
"returned":"always",
"caseExact":false
}
]
}
]
}
]
Flow Magister implementatie
Bij de toevoeging, wijziging of verwijdering van een ECK iD van een leerling, student of docent wordt een SCIM uitwisseling gestart. Over het algemeen communiceert Magister via de SCIM-koppeling binnen 20 minuten nadat een wijziging gemaakt is, tenzij de school de automatische uitwisseling uit heeft staan. Wanneer er fouten in de uitwisseling optreden wordt de volgende uitwisseling steeds verder uitgesteld tot een maximum van één week (back-off principe).
Het onderstaande diagram geeft de flow weer. In het geval van een toevoeging of wijziging gebruikt Magister een search om vast te stellen of de betreffende persoon aan de kant van de service provider bestaat. Afhankelijk van het resultaat van de search wordt dan een 'POST' of een 'PUT' gedaan. Voor een verwijdering gebruikt Magister het id dat de service provider eerder teruggeven heeft bij een 'POST' of een 'PUT'. Daarmee wordt een 'DELETE' uitgevoerd voor de verwijdering.
Randvoorwaarden aan de SCIM-implementatie
Magister is als SCIM client voor ECK iD uitsluitend een leverancier van identiteiten, het is niet mogelijk identiteiten aan te leveren aan Magister via deze weg.
Als uw SCIM ontvanger ('service provider') meerdere scholen bedient, dan moet de service provider er zorg voor dragen dat de ECK iD's per school aangeleverd kunnen worden. Een goede mogelijkheid is om dit met gescheiden endpoints te doen.
Om identiteiten te kunnen ontvangen moet uw SCIM ontvanger ('service provider') minimaal:
- Het endpoint voor de resource 'EduUsers' implementeren
- De 'POST'-operatie op het EduUsers-endpoint implementeren (https://tools.ietf.org/html/rfc7644#page-11)
- De 'POST'-operatie om te zoeken op het EduUsers-endpoint implementeren (https://tools.ietf.org/html/rfc7644#page-27; in de body zal als filter 'eckId eq \"<ECK iD>\"' worden gebruikt)
- (warning) Er is gekozen voor zoeken met behulp van 'POST' om zoveel als mogelijk te voorkomen dat een ECK iD wordt opgenomen in logbestanden
- De 'PUT'-operatie op het EduUsers-endpoint implementeren (https://tools.ietf.org/html/rfc7644#page-30)
- TLS 1.3 gebruiken op de geïmplementeerde SCIM-endpoints
- OAuth 2.0 authenticatie implementeren voor de geïmplementeerde endpoints, waarbij Magister uitsluitend authenticatie op basis van de client credentials flow ondersteunt.
Om identiteiten te kunnen verwijderen moet uw SCIM ontvanger ('service provider') daarnaast minimaal:
- De 'DELETE'-operatie op het EduUsers-endpoint implementeren (https://datatracker.ietf.org/doc/html/rfc7644#section-3.6)
- Altijd het gebruikers-id teruggeven op POST en PUT operaties op het endpoint voor de 'EduUsers' resource.
Foutmeldingen in Magister relateren aan uw eigen logging
Magister stuurt een 'X-Correlation-Id' header mee. De correlatie-id in deze header wordt ook in de foutmeldingen in Magister getoond en geeft u dus de mogelijkheid om de melding te relateren aan uw logging.
Gegevens die de school nodig heeft
De beheerder van de school kan eenvoudig in web een nieuwe automatische SCIM-koppeling aanmaken voor het versturen van ECK iD's.
Het EduUsers endpoint moet beginnen met 'https' en eindigen met 'eduusers'. Dit endpoint is beveiligd met een token.
De rest van de configuratie betreft dit token.
U levert een OAuth 2.0 token endpoint waar met de aangeleverde client credentials (ID en secret) en eventuele scopes een token opgehaald kan worden.
Indien uw implementatie het verwijderen van identiteiten niet ondersteunt, moet u aangeven dat de school het vinkje "Wanneer een account verwijderd is, deze ook bij de Service Provider verwijderen" uit moet zetten.
