SCIM provisioning

Curriculate biedt een SCIM 2.0-endpoint zodat de IT-beheerder van een school of organisatie gebruikers in zijn eigen tenant kan aanmaken, bijwerken en deactiveren vanuit een identity provider (IdP) — zonder dat de Curriculate-supportafdeling tussenkomst nodig heeft.

Werkt met elke SCIM 2.0-compatibele provider, met geteste setups voor Microsoft Entra ID en Google Workspace.

Voordat je begint

• Je hebt de rol admin binnen je tenant in Curriculate. Alleen tenant-admins kunnen SCIM-tokens beheren.
• Je hebt beheerderstoegang tot je identity provider (Entra ID of Google Workspace).
• De gebruikers in je IdP hebben een e-mailadres, voornaam en achternaam ingevuld — dit zijn de attributen die Curriculate gebruikt.

Authenticatie in Curriculate

Curriculate werkt met magic links (een eenmalige inlog-link per e-mail) en heeft geen wachtwoorden. SCIM-provisioning levert dan ook geen wachtwoord aan — nieuwe gebruikers loggen direct in via de magic link.

1. Genereer een SCIM-token in Curriculate

1. Log in op Curriculate en ga naar Instellingen → SCIM tokens.

2. Klik op Create token.

3. Geef het token een herkenbare naam, bijvoorbeeld Entra ID productie of Google Workspace. De naam is alleen voor jouzelf — om later te zien welk token bij welke IdP hoort.

4. Klik op Create token. Je krijgt nu eenmalig het volledige token te zien in een melding Token created. Het token begint altijd met scim_, bijvoorbeeld:

   scim_aBc123XyZ...

5. Kopieer het token direct. Curriculate slaat alleen een hash op — je kunt het token later niet meer inzien. Bewaar het veilig (bijvoorbeeld in een wachtwoordkluis) en plak het straks in je IdP.

Opgepast

Verlies je het token? Genereer dan een nieuw token en intrek het oude via de Revoke-knop in dezelfde Instellingenpagina.

2. Noteer je SCIM-endpoint

Je SCIM-endpoint heeft altijd de vorm:

https://<jouw-curriculate-domein>/scim/v2

Voor de productieomgeving is dat doorgaans:

https://app.curriculate.nl/scim/v2

Dit is de Tenant URL die je IdP nodig heeft. Je hoeft hier geen organisatie-id of slug aan toe te voegen — Curriculate herkent je tenant automatisch aan het bearer token.

3. Configureer je identity provider

Microsoft Entra ID

1. Open de Microsoft Entra admin center → Identity → Applications → Enterprise applications.

2. Klik op New application → Create your own application. Kies Integrate any other application you don’t find in the gallery (Non-gallery), geef de app een naam (bijv. Curriculate) en maak deze aan.

3. Open de nieuwe applicatie en ga naar Provisioning. Kies bij Provisioning Mode voor Automatic.

4. Vul onder Admin Credentials in:

   Veld	Waarde
   Tenant URL	https://app.curriculate.nl/scim/v2
   Secret Token	Het token uit stap 1 (begint met scim_)

5. Klik op Test Connection. Entra ID controleert nu of de credentials geldig zijn. Krijg je een groene melding, ga dan verder. Krijg je een foutmelding, controleer dan het token en de URL.

6. Open Mappings → Provision Microsoft Entra ID Users en zorg dat minimaal de volgende attributen worden gemapt (default mapping voldoet meestal):

   Entra-attribuut	SCIM-attribuut
   userPrincipalName	userName
   displayName	displayName
   givenName	name.givenName
   surname	name.familyName
   mail	emails[type eq "work"].value
   Switch([IsSoftDeleted], , "False", "True", "True", "False")	active
   objectId	externalId

   Tip

   Verwijder eventuele mappings naar roles, groups of password — die ondersteunt Curriculate niet.

7. Onder Settings zet je Provisioning Status op On en kies je een Scope (alle gebruikers, of enkel toegewezen gebruikers/groepen).

8. Sla op. Entra ID start binnen 40 minuten met de eerste cyclus, of je kunt handmatig Provision on demand uitvoeren om één gebruiker direct te testen.

Google Workspace

1. Open de Google Admin Console → Apps → Web and mobile apps.

2. Klik op Add app → Add custom SAML app en geef de app een naam (bijv. Curriculate). Doorloop de SAML-stappen of sla ze over als je geen SSO instelt — auto-provisioning kan ook zonder SAML.

3. Open de aangemaakte app en kies Auto-provisioning → Configure auto-provisioning.

4. Vul in:

   Veld	Waarde
   Access token	Het token uit stap 1 (begint met scim_)
   Endpoint URL	https://app.curriculate.nl/scim/v2

5. Klik op Continue. Google verifieert het endpoint via een GET /scim/v2/ServiceProviderConfig-aanroep.

6. Bij Attribute mapping zorg je dat minimaal het volgende klopt:

   Google-attribuut	SCIM-attribuut
   Primary email	userName
   First name	name.givenName
   Last name	name.familyName
   Primary email	emails[0].value
   (constant true)	active

7. Bij Provisioning scope kies je welke gebruikers (of organisatie-units) onder de auto-provisioning vallen.

8. Bij Deprovisioning kies je wat er gebeurt als een gebruiker uit Google wordt verwijderd of gedeactiveerd. Het meest gebruikte profiel is Suspend the user in de doelapp — dit komt overeen met active = false in Curriculate.

9. Klik op Finish en daarna op Activate om de synchronisatie te starten.

4. Test de synchronisatie

Na het inschakelen van provisioning verschijnen nieuwe gebruikers automatisch in Curriculate onder Instellingen → Gebruikers.

Controleer:

• Nieuwe gebruiker in je IdP → verschijnt binnen enkele minuten in Curriculate.
• Voornaam of achternaam wijzigen in je IdP → wordt bijgewerkt in Curriculate.
• Gebruiker deactiveren in je IdP → active wordt false in Curriculate; de gebruiker kan niet meer inloggen.
• Gebruiker verwijderen uit je IdP → de gebruiker wordt uit Curriculate verwijderd (afhankelijk van de deprovisioning-instellingen van je IdP).

Attribute mapping: SCIM ↔ Curriculate

Curriculate bewaart de volgende velden via SCIM. Andere SCIM-attributen worden genegeerd.

SCIM-attribuut	Curriculate-veld	Schrijfbaar	Toelichting
userName	E-mailadres	Ja	Verplicht; uniek per tenant.
displayName	Volledige naam	Ja	Verplicht.
name.givenName	Voornaam	Ja
name.familyName	Achternaam	Ja
emails[0].value	E-mailadres	Ja	Eerste primaire work e-mail wordt gebruikt.
active	Actief	Ja	false deactiveert de gebruiker.
externalId	Externe ID	Ja	Aanbevolen — voor stabiele koppeling.
id	Curriculate-ID	Nee	Door Curriculate toegekend (UUID).
meta.created	Aangemaakt op	Nee	ISO 8601.
meta.lastModified	Bijgewerkt op	Nee	ISO 8601.

Niet ondersteund

• SCIM Groups — rollen worden binnen Curriculate beheerd, niet via SCIM.
• Wachtwoorden — Curriculate gebruikt magic-link authenticatie.
• Meerdere e-mailadressen — alleen de primaire work e-mail wordt opgeslagen.

SCIM API-referentie

Alle endpoints staan onder https://app.curriculate.nl/scim/v2/... en verwachten:

Authorization: Bearer scim_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/scim+json
Content-Type: application/scim+json

Discovery (publiek, zonder token)

Methode	Pad	Doel
GET	/scim/v2/ServiceProviderConfig	Ondersteunde features.
GET	/scim/v2/Schemas	Lijst van schema’s.
GET	/scim/v2/ResourceTypes	Beschikbare resource types (alleen User).

Users

Methode	Pad	Doel
GET	/scim/v2/Users	Lijst gebruikers in je tenant. Ondersteunt filter, startIndex, count.
POST	/scim/v2/Users	Maak een gebruiker aan in je tenant.
GET	/scim/v2/Users/{id}	Eén gebruiker ophalen.
PUT	/scim/v2/Users/{id}	Volledige vervanging van een gebruiker.
PATCH	/scim/v2/Users/{id}	Partiële update via Operations (op: replace).
DELETE	/scim/v2/Users/{id}	Verwijder een gebruiker definitief.

Paginering: standaard count is 25, maximum is 200.

Filter-voorbeelden (standaard SCIM-syntax):

?filter=userName eq "docent@school.nl"
?filter=active eq true
?filter=externalId eq "abc-123"

Voorbeeld: gebruiker aanmaken

POST /scim/v2/Users HTTP/1.1
Host: app.curriculate.nl
Authorization: Bearer scim_xxx...
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "j.dejong@school.nl",
    "displayName": "Jan de Jong",
    "name": {
        "givenName": "Jan",
        "familyName": "de Jong"
    },
    "emails": [
        { "value": "j.dejong@school.nl", "type": "work", "primary": true }
    ],
    "active": true,
    "externalId": "entra-7f3c..."
}

Antwoord: 201 Created met de volledige SCIM-resource, inclusief de toegekende id.

Voorbeeld: gebruiker deactiveren

PATCH /scim/v2/Users/{id} HTTP/1.1
Authorization: Bearer scim_xxx...
Content-Type: application/scim+json

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        { "op": "replace", "path": "active", "value": false }
    ]
}

Foutresponses

Alle fouten volgen de SCIM 2.0 error-schema:

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
    "status": "401",
    "detail": "Invalid SCIM token."
}

Code	Wanneer
401	Ontbrekend, ongeldig of ingetrokken bearer token.
403	Tenant is gearchiveerd.
404	Resource bestaat niet of hoort bij een andere tenant.
409	Conflict, bijvoorbeeld een dubbel userName.
400	Validatiefout in het verzoek.

Token intrekken

Wil je een token intrekken (bijvoorbeeld bij vertrek van een beheerder of bij een vermoeden van lekken)?

1. Ga naar Instellingen → SCIM tokens.
2. Klik op Revoke naast het betreffende token.
3. Vanaf dat moment leveren alle SCIM-verzoeken met dit token een 401-fout op. Ingetrokken tokens blijven zichtbaar in de lijst zodat je kunt zien wanneer ze actief waren.

Beperkingen en quirks

• Geen Groups-resource. Rollen worden in Curriculate beheerd, niet via SCIM.
• Geen wachtwoord. Authenticatie gebeurt via magic links.
• DELETE is permanent. Wil je een gebruiker tijdelijk uitschakelen, gebruik dan PATCH met active = false.
• Eén tenant per token. Het token bepaalt onomstotelijk om welke tenant het gaat — cross-tenant verzoeken leveren 404 op.
• Responses zijn “flat”. Curriculate gebruikt omit_main_schema_in_return zodat het hoofd-schema niet opnieuw in elke response wordt opgenomen — dit is conform RFC 7644 §3.3.2 en werkt out-of-the-box met Entra ID en Google.