Skip to main content

Adding users via Microsoft Entra ID

A step-by-step guide to adding users to your online academy from Microsoft Entra ID

Written by Floor Takman

To add users from Microsoft Entra ID (formerly Azure Active Directory) to another system, Microsoft uses the SCIM protocol. SCIM lets you add users to your online academy (provisioning) by matching fields and synchronizing them automatically.

This article walks you through the key steps.

Please note: for exact details, always refer to Microsoft's support page. Microsoft developed the software and can provide further support.

Important!

When your academy was created, a default company and department were created along with it. This company, which carries the name of your academy, is included in the SCIM token. Users are linked to this company whenever the integration doesn't send a company. Make sure this company is never deleted. If it is, the SCIM integration will stop working.

Setting up the integration: overview

Setting up the SCIM integration involves a few steps, all of which are explained in this article. Here's a brief overview.

Step 1: Create the application

In this step, you create the application in Entra. The SCIM integration is configured within this application. You'll need the SCIM token you received from Rakoo. Don't have it yet? Request it via support@rakoo.com or through your Customer Success Manager.

Step 2: Configure the application

In this step, you configure the application. You specify which fields in Entra should be sent to which fields in Rakoo. This is called the mapping.

Step 3: Add users and/or groups to the SCIM configuration

In this step, you choose which users or groups of users will be added to your academy automatically through the SCIM integration.

Step 4: Test the integration and go live

In this step, you test the integration to check that everything is set up correctly. Then you turn it on so users are added to your academy automatically.

Step 1: Create the application

The first step in setting up a SCIM integration is to create a new application in Microsoft Entra ID. To do this, follow the steps below:

  1. Open Microsoft Entra ID.

  2. Go to 'Enterprise applications'.

  3. Select 'New application'.

    1. Choose 'Create your own application'.

    2. Enter a name and select 'Integrate any other application you don't find in the gallery (Non-gallery)'. Then click 'Create'.

  4. Once the new enterprise application has been created, you'll be taken straight to its overview page, where you can complete the next steps.

  5. Under 'Manage', go to 'Provisioning'.

  6. Choose 'Connect your application'.

  7. Fill in the required details:

    1. Authentication method: leave this set to Bearer authentication.

    2. Tenant URL: enter https://api.rakoo.com/api/v2/external/scim.

    3. Secret token

    The SCIM token is provided by Rakoo. Haven't received it yet? Contact support@rakoo.com or your Customer Success Manager.

  8. Click 'Test connection'.

  9. Was the connection test successful? Then click 'Create'. This doesn't make the SCIM integration live yet; you'll do that at a later stage. Was the connection test unsuccessful? Check the details you entered and the error message, then try again.

Step 2: Configure the application

Mapping Entra fields to Rakoo fields

Entra ID holds a set of fields with information about each user. In Rakoo, each user also has a number of fields that must or can be filled in. For each Entra field, you specify which Rakoo field it should be linked to. From here on, we'll call this the mapping. The mapping determines which Entra field is used to fill each field in Rakoo.

Once you've created the application, check the mapping and set it up the way you want. Below, you'll find which target attribute (customappsso) fills each Rakoo field. The data flows as follows: Microsoft Entra ID attribute > customappsso attribute > Rakoo field.

The link between each Rakoo field and its customappsso attribute is fixed. In the mapping, you decide which Entra source attribute is sent to which customappsso target attribute.

  • Please note: you can't, and don't need to, enter the Rakoo field in the SCIM configuration. It's only there to show which of the other fields correspond to what you'll see in Rakoo.

  • Please note: you can ignore the other fields that appear in the SCIM configuration by default. Don't delete them; Rakoo will simply ignore them.

Microsoft Entra ID attribute

customappsso attribute

Rakoo field

mailNickname*

externalId

User ID

companyId** (This is fixed in the token and is required for the configuration)

Automatically filled in by Rakoo.

department* (String value. E.g., 'Department X')

urn:ietf:params:scim:schemas:extension:enterprise:2.0:

User:department

Department

userPrincipalName*

userName

Email (must match the value sent for 'emails[type eq "work"].value')

mail*

emails[type eq "work"].value

Email (must match the value sent for 'userName')

givenName*

name.givenName

First name

surname*

name.familyName

Last name

preferredLanguage (This is a language code, e.g., en or nl-NL

preferredLanguage

Language

jobTitle

title

Function (If the function does not exist in Rakoo, it will be created)

employeeOrgData.costCenter (String value. E.g., ‘administration’)

urn:ietf:params:scim:schemas:extension:enterprise:2.0:

User:costCenter

Cost center

companyName (String value. E.g., 'Company X')

urn:ietf:params:scim:schemas:extension:enterprise:2.0:

User:organization

Company

Attribute of your choice (String value, multiple values. E.g., [“team1”,”team2”])

urn:ietf:params:scim:schemas:extension:enterprise:2.0:

User.teams

Team

Own attribute***

name.middleName

Middle name

manager

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value

You can assign one manager to a user. Existing managers who have one-on-one access to that user will be disconnected.

* These fields are required.

** If you want to assign users to different companies in Rakoo, you can use 'companyName' to link users to other companies. If companyName isn't provided, the company included in the SCIM token is used.

*** Rakoo supports the customappsso attribute name.middleName. Microsoft doesn't have a standard user-level field for name prefixes. If you like, you can configure a field for this yourself. If you don't, the prefix will be included in the last name field in Rakoo.

Important!

The email address sent for userName and emails[type eq "work"].value must be the same for each user in Entra. Rakoo stores one email address per user. If we receive two different email addresses, we can't tell which one to use. That's why we require the same value for both attributes; if they differ, the integration won't work. This is also case-sensitive.

By default, this works fine if mail and userPrincipalName contain the same email address for each user in Entra. If these two fields differ for some users, you can set up the mapping so that we still receive the same value for both. In the example below, the mapping is set up so that the value of userPrincipalName is sent for emails[type eq "work"].value.

If a company, department, team or function sent to Rakoo doesn't exist yet, it will be created automatically.

Adjusting the mapping to your needs

The mapping is already filled in by default. Want to send a different Entra field to a particular Rakoo field? You can change the mapping of an attribute so that a different source attribute is sent to a target attribute. We explain how below.

Some target attributes (customappsso) aren't included in the attribute mapping by default. Further on in this article, we explain how to add them for each situation. This applies to mapping the name prefix, cost center, company, team, and manager.

Changing an attribute

  1. Under 'Manage', go to 'Attribute mapping'.

  2. Click the pencil icon next to the Target attribute (customappsso) whose Source attribute (Microsoft Entra ID) you want to change.

  3. Change the Source attribute (Microsoft Entra ID) and click 'Apply'.

  4. Leave the other fields as they are.

  5. Click 'Apply'.

Example

By default, the Entra field jobTitle is sent to the customappsso attribute title. The job title field in Rakoo is filled from the customappsso attribute title.

Say you want to fill the job title field in Rakoo with the Entra field employeeType instead of jobTitle. In that case, you change the mapping so that the target attribute title is filled from the source attribute employeeType.

Adding an attribute

Some target attributes (customappsso) aren't included in the attribute mapping by default. You can add them yourself. Below, we explain how to do this for each target attribute.

Mapping managers

You can link managers through the SCIM protocol. The manager must already exist as a user in Rakoo. If needed, this user will automatically be made a manager. The setup required for this isn't part of the default configuration. Follow the steps below to map managers to Rakoo.

Once a user has been made a manager through SCIM, this can only be undone manually in Rakoo.

  1. Under 'Manage', go to 'Attribute mapping'.

  2. Go to 'Show advanced options' and then 'Edit attribute list for customappsso'.

  3. At the bottom, click 'Add new attribute'.

  4. Add urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value and set the type to 'Reference'.

  5. Add urn:ietf:params:scim:schemas:extension:enterprise:2.0:User as reference.

  6. Click 'Save' at the bottom left.

  7. Click the pencil icon next to the Source Attribute (Microsoft Entra ID) 'manager' to edit it.

  8. Under 'Target attribute (customappsso)', select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager.value and set the following:

    1. Match objects using this attribute: No

    2. Apply this mapping: Always

  9. Click 'Apply'.

  10. In the attribute mapping overview, click 'Save'.

Mapping companies

A user in Rakoo must always be linked to a company. If no company is sent from Entra, the user is linked to the default company included in the SCIM token. You can also send, for example, a user's companyName from Entra to the company field in Rakoo. This mapping isn't in the overview by default, so you'll need to add it yourself. To do so, follow these steps.

  1. Under 'Manage', go to 'Attribute mapping'.

  2. Click 'Add attribute mapping'.

  3. Under 'Target attribute (customappsso)', select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization.

  4. Under 'Source attribute (Microsoft Entra ID)', select companyName. You can also select a different Entra field here, which will then be sent to the company field in Rakoo. Also set the following:

    1. Match objects using this attribute: No

    2. Apply this mapping: Always

  5. Click 'Add'.

  6. In the attribute mapping overview, click 'Save'.

Mapping teams

Team isn't a standard user field in Entra, but it is available as a target attribute (customappsso). This lets you send a field of your choice to the team field in Rakoo. It isn't included in the attribute mapping by default. Follow the steps below to add it.

  1. Under 'Manage', go to 'Attribute mapping'.

  2. Go to 'Show advanced options' and then 'Edit attribute list for customappsso'.

  3. At the bottom, click 'Add new attribute'.

  4. Add urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.teams and set the type to 'String'. Tick the box in the 'Multi-value' column.

  5. Click 'Save' at the bottom left.

  6. Click 'Add attribute mapping'.

  7. Under 'Target attribute (customappsso)', select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.teams.

  8. Under 'Source attribute (Microsoft Entra ID)', select the Entra field you want to send to the team field in Rakoo. Also set the following:

    1. Match objects using this attribute: No

    2. Apply this mapping: Always

  9. Click 'Add'.

  10. In the attribute mapping overview, click Save.

Mapping cost centers

Cost center isn't included in the attribute mapping by default, but you can add it so you can send an Entra field to the cost center field in Rakoo. To do so, follow these steps.

  1. Under 'Manage', go to Attribute mapping.

  2. Click 'Add attribute mapping'.

  3. Under 'Target attribute (customappsso)', select urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter.

  4. Under 'Source attribute (Microsoft Entra ID)', select employeeOrgData.costCenter. You can also select a different Entra field here, which will then be sent to the cost center field in Rakoo. Also set the following:

    1. Match objects using this attribute: No

    2. Apply this mapping: Always

  5. Click 'Add'.

  6. In the attribute mapping overview, click 'Save'.

Mapping name prefixes

Rakoo supports a separate name prefix field (such as "van" or "de" in Dutch names). However, Microsoft doesn't have a standard user-level field for this. You can configure a field for it yourself and then send it to the name prefix field in Rakoo. Below, we explain how to set up this mapping. If you don't, the prefix will be included in the 'Last name' field in Rakoo.

  1. Under 'Manage', go to 'Attribute mapping'.

  2. Go to 'Show advanced options' and then 'Edit attribute list for customappsso'.

  3. At the bottom, click 'Add new attribute'.

  4. Add name.middleName and set the type to 'String'.

  5. Click 'Save' at the bottom left.

  6. Click 'Add attribute mapping'.

  7. Under 'Target attribute (customappsso)', select name.middleName.

  8. Under 'Source attribute (Microsoft Entra ID)', select the Entra field you configured for this and want to send to the name prefix field in Rakoo. Also set the following:

    1. Match objects using this attribute: No

    2. Apply this mapping: Always

  9. Click 'Add'.

  10. In the attribute mapping overview, click 'Save'.

The unique identifier in the SCIM integration is the user's technical user ID in Rakoo. This is the ID shown in the URL when you edit a user in Rakoo. Through the integration, Entra also stores this ID for each user. It's used to update existing users in Rakoo.

Step 3: Add users and/or groups to the SCIM configuration

Now that the mapping is set up, you need to specify exactly which users should be added to Rakoo. You can do this with individual users and/or user groups (Group). Once the integration is live, these users will be added to your online academy. Follow the steps below to assign users and/or groups to the SCIM application.

  1. Go to 'Enterprise applications'.

  2. Open your SCIM application.

  3. Under 'Manage', go to 'Users and groups'.

  4. Click 'Add user/group'.

  5. Select the users and/or groups you want to add and click 'Assign'.

Please note: 'Group' here refers to a user group, not a field that can be sent to Rakoo.

Step 4: Test the integration and go live

Testing the integration

It's a good idea to start by adding one or a few users through the SCIM integration to check that everything works. To do so, follow these steps.

  1. Go to 'Enterprise applications'.

  2. Open your SCIM application.

  3. Click 'Provisioning' and then 'Provision on demand'.

  4. Select the user and click 'Provision'.

Going live

Once everything is set up correctly, you can make the SCIM integration live. To do so, follow these steps.

  1. Go to 'Enterprise applications'.

  2. Open your SCIM application.

  3. Click 'Provisioning'.

  4. Choose 'Start provisioning'.

Changing the integration

Follow the steps below to change the integration.

  1. Go to Enterprise applications.

  2. Open your SCIM application.

  3. Click 'Start provisioning'.

  4. Depending on what you want to change, click 'Attribute mapping' or 'Users and groups'.

Do you have questions about setting up the SCIM integration, or are you stuck? Please contact support.

Did this answer your question?

Related Articles