Voor het toevoegen van gebruikers vanuit Microsoft Entra ID (voorheen Azure Active Directory) aan een ander systeem heeft Microsoft het SCIM-protocol ontwikkeld. Hiermee kan je gebruikers toevoegen (provisioning) aan je online academy door matching van velden en automatische synchronisatie.
In dit artikel vind je een handleiding die je door de belangrijkste stappen leidt.
Let op: voor exacte informatie kun je altijd het best de supportpagina van de Microsoft raadplegen. Microsoft heeft de software ontwikkeld en kan verdere ondersteuning verlenen.
Let op!
Bij het aanmaken van jullie academy is er een standaard bedrijf en afdeling aangemaakt. Dit bedrijf – dat de naam van jullie academy heeft – wordt opgenomen in het SCIM-token. Aan dit bedrijf worden gebruikers gekoppeld als er vanuit de koppeling geen bedrijf wordt meegestuurd. Let erop dat dit bedrijf niet verwijderd wordt. Gebeurt dit wel, dat werkt de SCIM-koppeling niet meer.
Opbouw voor het aanmaken van de koppeling
Voor het inrichten van de SCIM-koppeling volg je een aantal stappen. Deze worden allemaal in dit artikel toegelicht. Hieronder volgt een korte toelichting van de te nemen stappen.
Stap 1: Aanmaken van de applicatie
In deze stap maak je de applicatie aan in Entra. Binnen deze applicatie wordt de SCIM-koppeling ingericht. Hiervoor heb je het SCIM-token nodig die je van Rakoo hebt ontvangen. Heb je deze nog niet? Dan kun je deze aanvragen via support@rakoo.com of via jouw Customer Success Manager.
Stap 2: Inrichten van de applicatie
In deze stap richt je de applicatie in. Je geeft aan welke velden uit Entra en doorgestuurd moeten worden naar een bepaald veld in Rakoo. Dit noemen we de mapping.
In deze stap geeft je aan welke gebruikers of groepen gebruikers er via de SCIM-koppeling automatisch toegevoegd gaan worden aan je academy.
Stap 4: De koppeling testen en live zetten
In deze stap test je de koppeling om te zien of de inrichting klopt. Daarna zet je de koppeling aan om ervoor te zorgen dat gebruikers automatsisch toegevoegd gaan worden aan je academy.
Stap 1: Aanmaken van de applicatie
De eerste stap in het aanmaken van een SCIM-koppeling is om binnen Microsoft Entra ID een nieuwe applicatie aan te maken. Hiervoor volg je onderstaande stappen:
Open Microsoft Entra ID.
Ga naar 'Bedrijfstoepassingen'.
Selecteer 'Nieuwe toepassing'.
Kies voor 'Uw eigen toepassing maken'.
Kies een naam en selecteer ‘Een willekeurige andere toepassing integreren die niet aanwezig is in de galerie (niet-galerie)’. Klik vervolgens op 'Maken'.
Na het aanmaken van de nieuwe bedrijfsapplicatie, wordt je gelijk naar de overzichtspagina ervan verwezen waar de volgende stappen uit te voeren zijn.
Ga via 'Beheren' en naar 'Inrichten'.
Kies voor 'Je toepassing verbinden'.
Vul de gevraagde gegevens in.
Verificatiemethode: Laat deze op 'Bearer-verificatie' staan.
Tenant URL: Dit is https://api.rakoo.com/api/v2/external/scim.
Token voor geheim.
Het SCIM-token is door Rakoo aangeleverd. Nog niet ontvangen? Neem dan contact op met support@rakoo.com of jouw Customer Success Manager.
Klik op 'Verbinding testen'.
Is de test verbinding geslaagd? Klik dan op 'Maken'. De SCIM-koppeling komt hiermee nog niet live te staan. Het live zetten van de koppeling doe je op een later moment.
Is de test verbinding niet geslaagd? Controleer de ingevulde gegevens en de foutmelding, en probeer het opnieuw.
Stap 2: Inrichten van de applicatie
Mapping Entra-velden naar Rakoo-velden
Entra ID geeft per gebruiker velden met informatie over deze gebruiker weer. In Rakoo heeft elke gebruiker ook een aantal velden die gevuld moeten en/of kunnen worden. Per Entra veld ga je aangeven aan welk Rakoo-veld deze gekoppeld moet worden, dit noemen we vanaf nu de mapping. Via deze mapping geef je aan vanuit welk veld uit Entra, een bepaald veld in Rakoo gevuld wordt.
Na het aanmaken van de applicatie controleer en richt je de mapping in naar de gewenste situatie. Hieronder staat welk doelkenmerk (customappsso) een Rakoo-veld vult. De datastroom loopt als volgt: Microsoft Entra ID-kenmerk > customappsso-kenmerk > Rakoo-veld.
De koppeling tussen Rakoo-veld en customappsso-kenmerk ligt vast; via de mapping bepaal je zelf welk Entra-bronkenmerk naar welk customappsso-doelkenmerk gestuurd wordt.
Let op: Het Rakoo-veld kun je en hoef je niet in te vullen in de SCIM-inrichting. Dit is ter indicatie welke van de andere velden corresponderen met wat je in Rakoo gaat terugzien.
Let op: De andere velden die (standaard) in de SCIM-inrichting staan, mag je negeren. Verwijder deze niet. Rakoo zal deze velden negeren.
Microsoft Entra ID-kenmerk (Bronkenmerk) | customappsso-kenmerk (Doelkenmerk) | Rakoo-veld |
mailNickname* | externalId | Gebruikers ID |
companyId** (deze staat vast in het token en is nodig voor de configuratie) |
| Automatisch ingevuld in Rakoo. |
department* (String-waarde. Voorbeeld 'Afdeling X') | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department | Afdeling |
userPrincipalName* | userName | E-mail (moet overeenkomen met de waarde die doorgestuurd wordt voor 'emails[type eq "work"].value') |
mail* | emails[type eq "work"].value | E-mail (moet overeenkomen met de waarde die wordt doorgestuurd voor 'userName') |
givenName* | name.givenName | Voornaam |
surname* | name.familyName | Achternaam |
preferredLanguage (Dit is een taal-code, bijvoorbeeld | preferredLanguage | Taal |
jobTitle | title | Functie (Indien functie nog niet bestaat in Rakoo, wordt deze aangemaakt) |
employeeOrgData.costCenter (String-waarde. Voorbeeld: 'Administratie') | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter | Kostenplaats |
companyName | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization | Bedrijf |
Zelf gekozen attribuut (String-waarde, meerdere waarden. Voorbeeld ["team1","team2"]) | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.teams | Team |
Eigen attribuut*** | name.middleName | Tussenvoegsel |
Manager
| urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value | Je kunt een gebruiker één manager geven. Bestaande managers die een-op-een toegang hebben tot die gebruiker worden ontkoppeld. |
* Deze velden zijn verplicht.
** Wil je gebruikers scharen onder verschillende bedrijven in Rakoo, dan kun je met companyName andere bedrijven toewijzen aan gebruikers. Als companyName niet wordt opgegeven, dan wordt de company gebruikt die in het SCIM-token verwerkt zit.
*** Rakoo ondersteunt het customappsso kenmerk name.middleName. Op gebruikersniveau in Microsoft is tussenvoegsel geen standaard veld. Je kunt hiervoor eventueel zelf een veld configureren. Wanneer je dit niet doet, wordt het tussenvoegsel bij achternaam geplaatst in Rakoo.
Let op!
Het e-mailadres dat doorgestuurd wordt voor userName en emails[type eq "work"].value moet overeenkomen per gebruiker in Entra. Rakoo kent één e-mailadres per gebruiker. Als we twee e-mailadressen krijgen doorgestuurd, weten we niet welke we moeten overnemen. Daarom vereisen we dat we voor deze twee kenmerken dezelfde waarde doorgestuurd krijgen, en werkt het niet als er een verschil in zit. Dit is ook hoofdlettergevoelig.
Dit gaat standaard goed als voor mail en userPrincipalName in Entra hetzelfde e-mailadres staat ingevuld per gebruiker. Als er per gebruiker verschil zit tussen deze twee velden, dan kan via de mapping ingesteld worden dat we toch voor beide velden dezelfde waarden ontvangen. In onderstaande voorbeeld is ingesteld dat voor emails[type eq "work"].value de waarde van userPrincipalName wordt doorgestuurd.
Mapping aanpassen naar gewenste situatie
De mapping staat vooraf al ingevuld. Wil je graag een ander veld uit Entra naar een bepaald veld in Rakoo sturen? Het is mogelijk om de mapping van een kenmerk aan te passen, zodat er een ander bronkenmerk naar een doelkenmerk doorgestuurd wordt. Dit leggen we hieronder uit.
Een aantal doelkenmerken (customappsso) staat niet standaard in de kenmerktoewijzing. Verderop in het artikel leggen we per situatie uit hoe je deze kunt toevoegen. Dit geldt voor het koppelen van tussenvoegsel, kostenplaats, bedrijf, team en manager.
Kenmerk wijzigen
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Klik bij het Doelkenmerk (customappsso) waarvan je het Bronkenmerk (Microsoft Entra ID) wil wijzigen op het potloodje.
Pas het Bronkenmerk (Microsoft Entra ID) aan en klik op 'Toepassen'.
De overige velden blijven ongewijzigd.
Klik op 'Toepassen'.
Voorbeeld
Standaard is het zo ingesteld dat het Entra-veld jobTitle doorgestuurd wordt naar het customappsso-kenmerk title. Het functie-veld in Rakoo wordt gevuld vanuit het customappsso-kenmerk title.
Stel dat je het functie-veld in Rakoo niet wil vullen met het Entra veld jobTitle, maar met employeeType, dan pas je in de mapping aan dat het doelkenmerk title wordt gevuld vanuit het bronkenmerk employeeType.
Kenmerk toevoegen
Een aantal doelkenmerken (customappsso) staat niet standaard in de kenmerktoewijzing. Deze kun je zelf toevoegen. Hieronder leggen we per doelkenmerk uit hoe je dit doet.
Manager koppelen
Het is mogelijk om via het SCIM-protocol managers te koppelen. De manager moet al als gebruiker bestaan in Rakoo. Als het nodig is wordt deze gebruiker automatisch manager gemaakt. De benodigde inrichting hiervan, staat niet in de standaard inrichting. Volg onderstaande stappen om managers te kunnen koppelen naar Rakoo.
Als een gebruiker eenmaal manager is gemaakt via SCIM, kan dit alleen handmatig in Rakoo ongedaan gemaakt worden.
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Ga naar 'Geavanceerde opties' en vervolgens naar 'Gebruikerskenmerken van customappsso bewerken'.
Klik onderaan op 'Nieuw kenmerk toevoegen'.
Voeg
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.valuetoe en kies bij type voor 'Verwijzing'.Voeg als referentie
urn:ietf:params:scim:schemas:extension:enterprise:2.0:Usertoe.
Klik links onderaan op 'Opslaan'.
Klik bij het Bronkenmerk (Microsoft Entra ID) 'manager' op het pennetje om te bewerken.
Selecteer bij 'Doelkenmerk (customappsso)'
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.valueen stel het volgende in:Objecten koppelen met dit kenmerk: Nee.
Deze toewijzing toepassen = Altijd.
Klik op 'Toepassen'.
Klik in het overzicht met kenmerktoewijzingen op 'Opslaan'.
Bedrijf koppelen
Een gebruiker in Rakoo moet altijd aan een bedrijf gekoppeld worden. Als er vanuit Entra geen bedrijf wordt meegegeven, dan wordt het standaard bedrijf gekoppeld dat in het SCIM-token is meegegeven. Daarnaast is het mogelijk om (bijvoorbeeld) de companyName van een gebruiker uit Entra, door te sturen naar het bedrijf-veld in Rakoo.
De mapping hiervoor staat niet standaard in het overzicht, en zul je zelf toe moeten voegen. Volg hiervoor de volgende stappen.
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Klik op 'Kenmerktoewijzing toevoegen'.
Selecteer bij 'Doelkenmerk (customappsso)'
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organizationSelecteer bij 'Bronkenmerk (Microsoft Entra ID)' companyName. Het is ook mogelijk om hier een ander Entra-veld te selecteren dat vervolgens naar het bedrijf-veld in Rakoo doorgestuurd wordt. Stel daarnaast het volgende in:
Objecten koppelen met dit kenmerk: Nee.
Deze toewijzing toepassen = Altijd.
Klik op 'Toevoegen'.
Klik in het overzicht met kenmerktoewijzingen op 'Opslaan'.
Team koppelen
Team is geen standaardveld bij gebruikers in Entra. Wel is team een doelkenmerk (customappsso). Hiermee kun je een zelf te bepalen veld, naar het team-veld in Rakoo sturen. Dit staat niet standaard in de kenmerktoewijzing. Volg de onderstaande stappen om dit toe te voegen.
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Ga naar 'Geavanceerde opties' en vervolgens naar 'Gebruikerskenmerken van customappsso bewerken'.
Klik onderaan op 'Nieuw kenmerk toevoegen'.
Voeg
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.teamstoe en kies bij type voor 'Tekenreeks'. Zet het vinkje in de kolom 'Meerdere waarden' aan.Klik links onderaan op 'Opslaan'.
Klik op 'Kenmerktoewijzing toevoegen'.
Selecteer bij 'Doelkenmerk (customappsso)'
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.teamsSelecteer bij 'Bronkenmerk (Microsoft Entra ID)' het Entra-veld dat je door wil sturen naar het team-veld in Rakoo. Stel daarnaast het volgende in:
Objecten koppelen met dit kenmerk: Nee.
Deze toewijzing toepassen = Altijd.
Klik op 'Toevoegen'.
Klik in het overzicht met kenmerktoewijzingen op 'Opslaan'.
Kostenplaats koppelen
Kostenplaats staat niet standaard in de kenmerktoewijzing. Wel kun je deze toevoegen, zodat je een Entra-veld naar het veld kostenplaats in Rakoo kunt sturen. Volg hiervoor de volgende stappen.
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Klik op 'Kenmerktoewijzing toevoegen'.
Selecteer bij 'Doelkenmerk (customappsso)'
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenterSelecteer bij 'Bronkenmerk (Microsoft Entra ID)' employeeOrgData.costCenter. Het is ook mogelijk om hier een ander Entra-veld te selecteren dat vervolgens naar het kostenplaats-veld in Rakoo doorgestuurd wordt. Stel daarnaast het volgende in:
Objecten koppelen met dit kenmerk: Nee.
Deze toewijzing toepassen = Altijd.
Klik op 'Toevoegen'.
Klik in het overzicht met kenmerktoewijzingen op 'Opslaan'.
Tussenvoegsel koppelen
Rakoo ondersteunt het veld tussenvoegsel. Dit is echter geen standaard veld op gebruikersniveau binnen Microsoft. Je kunt hiervoor zelf een veld configureren. Dit veld kun je vervolgens doorsturen naar tussenvoegsel in Rakoo. Hieronder leggen we uit hoe je deze mapping inricht. Wanneer je dit niet doet, wordt het tussenvoegsel bij de 'Achternaam' geplaatst in Rakoo.
Ga onder 'Beheren' naar 'Kenmerktoewijzing'.
Ga naar 'Geavanceerde opties' en vervolgens naar 'Gebruikerskenmerken van customappsso bewerken'.
Klik onderaan op 'Nieuw kenmerk toevoegen'.
Voeg
name.middleNametoe en kies bij type voor 'Tekenreeks'.Klik links onderaan op 'Opslaan'.
Klik op 'Kenmerktoewijzing toevoegen'.
Selecteer bij 'Doelkenmerk (customappsso)'
name.middleName.Selecteer bij 'Bronkenmerk (Microsoft Entra ID)' het Entra-veld dat je hiervoor geconfigureerd hebt, en dat je door wil sturen naar het tussenvoegsel-veld in Rakoo. Stel daarnaast het volgende in:
Objecten koppelen met dit kenmerk: Nee.
Deze toewijzing toepassen = Altijd.
Klik op 'Toevoegen'.
Klik in het overzicht met kenmerktoewijzingen op 'Opslaan'.
De unieke identifier binnen de SCIM-koppeling is het technische user ID van de gebruiker in Rakoo. Dit is het ID dat in de URL staat als je een gebruiker in Rakoo bewerkt. Via de koppeling is dit ID ook bekend binnen Entra per gebruiker. Op basis hiervan zal een bestaande gebruiker in Rakoo geüpdatet worden.
Stap 3: Gebruikers en/of groepen toevoegen in SCIM-inrichting
Nu de mapping is ingericht, moet je nog aangeven welke gebruikers precies toegevoegd moeten worden aan Rakoo. Dit kan met losse gebruikers en/of met gebruikersgroepen (Groep). Deze gebruikers zullen als de koppeling live staat, worden toegevoegd aan je online academy. Volg de volgende stappen om gebruikers en/of groepen toe te wijzen aan de SCIM-applicatie.
Ga naar 'Bedrijfstoepassingen'.
Open jouw SCIM-applicatie.
Ga onder 'Beheren' naar 'Gebruikers en groepen'.
Klik op 'Gebruiker/groep toevoegen'.
Selecteer de toe te voegen gebruikers en/of groepen en klik op 'Toewijzen'.
Let op: Met 'Groep' wordt hier een gebruikersgroep bedoeld. En niet een veld dat kan worden doorgestuurd naar Rakoo.
Stap 4: De koppeling testen en live zetten
Koppeling testen
Het is verstandig om eerst één of enkele gebruikers toe te voegen via de SCIM-koppeling, om te kijken of alles goed gaat. Volg hiervoor de volgende stappen.
Ga naar 'Bedrijfstoepassingen'.
Open jouw SCIM-applicatie.
Klik op 'Inrichten' en vervolgens op 'Inrichten op aanvraag'.
Selecteer de gewenste gebruiker en klik op 'Provision'.
De koppeling live zetten
Als alles goed is ingericht, kun je de SCIM-koppeling live zetten. Doorloop hiervoor de volgende stappen.
Ga naar 'Bedrijfstoepassingen'.
Open jouw SCIM-applicatie.
Klik op 'Inrichten'.
Kies voor 'Inrichten starten'.
De koppeling wijzigen
Volg onderstaande stappen om de koppeling te wijzigen.
Ga naar 'Bedrijfstoepassingen'.
Open jouw SCIM-inrichting.
Klik op 'Inrichten'.
Klik afhankelijk van wat je wil wijzigen op 'Kenmerktoewijzing' of 'Gebruikers en groepen'.
Heb je vragen over het inrichten van de SCIM-koppeling of kom je ergens niet uit? Neem dan contact met support.