With a SCIM connection, your organisation sends new employees, changes and leavers to 2LRN4 itself, from Microsoft Entra ID, Okta or Google. You don't need to give 2LRN4 access to your own environment: you decide who and what is sent. The connection is free and works with every package.

This page describes the setup in Microsoft Entra. Okta and Google use the same details (the tenant URL and the secret token from the portal); only the screens differ.

SCIM works one way. Changes flow from your user directory to 2LRN4, never the other way round.

What the connection does

• New employee. When you assign someone to the app in Entra, 2LRN4 creates the account and enrols it in the organisation's learning programme.
• Change. Name, department, preferred language and role are updated. If a department doesn't exist yet, 2LRN4 creates it.
• Leaver. When you remove someone from the app, or disable the account, the employee is set to inactive in 2LRN4. An inactive account can no longer sign in and does not count towards your licences. Progress and certificates are kept, so you can still show later who completed which training. After the period your organisation chooses in its settings (365 days by default), 2LRN4 deletes the inactive account automatically. The contact person receives a monthly overview with the training history of the deleted accounts, and the user list shows in advance when an account will be deleted.
• Role. An app role in Entra determines whether someone becomes a learner, manager or administrator (see Roles below).

2LRN4 only keeps what it needs: name, email address, department, preferred language, role and whether the account is active. Other details Entra sends, such as job title or phone number, are not stored.

How this differs from user synchronisation

2LRN4 also offers user synchronisation with Microsoft Entra. There, 2LRN4 fetches the users itself, using an app registration with read access to your users and groups. SCIM works the other way: Entra sends the data, and 2LRN4 gets no read access to your tenant. That is why many security teams prefer SCIM.

Use one of the two per organisation, not both at once. The synchronisation sets employees to inactive when they are not in its group, even if SCIM manages them.

Before you start

1. Switch the connection on. As a customer administrator, go to Integrations and then SCIM connection in the portal, tick SCIM connection on and click Save. You then see two details:
   • the tenant URL, the address Entra sends the data to;
   • a secret token that starts with scim_. Treat it like a password: with the token, accounts in your organisation can be created and disabled. The portal shows it once. If you lose it, create a new one with Create new token; the old one stops working immediately.
2. Set the roles you want to use. For example: app role Administrator becomes customer administrator, app role Manager becomes manager. You set this on the same page, under Role rules. Anyone without a matching role gets the default role, usually learner. You can also use the fixed values listed under Roles; then you don't need to set anything.
3. Check your email domains. 2LRN4 only accepts addresses on the domains set up for your organisation. Let us know about new domains in advance.
4. Check your Entra ID licence. Assigning individual users works in every edition of Entra ID, including the free one. Assigning groups requires Microsoft Entra ID P1 or P2.

Step 1: create the app

1. Go to entra.microsoft.com and open Enterprise applications.
2. Click New application, then Create your own application.
3. Give the app a name, for example 2LRN4.
4. Choose Integrate any other application you don't find in the gallery (Non-gallery) and click Create.

Step 2: create app roles (for the roles)

Skip this step if everyone may become a learner.

1. Open App registrations, choose All applications and open the app you just created.
2. Go to App roles and click Create app role.
3. Fill in Display name and Value, for example Administrator for both. Under Allowed member types choose Users/Groups, add a description and click Apply.
4. Repeat this for every role you want to use, for example Manager. The value must match exactly the value in your role rules in the portal, or one of the fixed values.

Step 3: make the connection

1. Go back to Enterprise applications, open the app and choose Provisioning.
2. Set the Provisioning Mode to Automatic.
3. Expand Admin Credentials. If Entra shows a message there that the credentials have moved, click the link in that message.
4. Keep the authentication method on Bearer authentication and fill in:
   • Tenant URL: the tenant URL from the portal.
   • Secret Token: the token you created in the portal.
5. Click Test Connection. If it succeeds, click Create or Save at the bottom.

Step 4: send the role along

By default Entra already sends name, email address, department and status. For the role you add one mapping.

1. In the app, open Provisioning and then Attribute mapping for users.
2. Click Add new mapping.
3. Under Mapping type choose Expression and enter as expression: SingleAppRoleAssignment([appRoleAssignments])
4. Choose as Target attribute: roles[primary eq "True"].value
5. Click Ok and then Save.

In the same list, check that userPrincipalName maps to userName. That is the address employees sign in with. If your email address differs from the sign-in address, let us know in advance.

Step 5: assign employees and test

1. In the app, open Users and groups and click Add user/group.
2. Pick one test user first, select the right app role and click Assign.
3. Go to Provisioning, choose Provision on demand, look up the test user and click Provision. Entra shows per step what was sent and whether it succeeded.
4. Check that the employee appears in 2LRN4 with the right department and role. If it's correct, assign the other employees or groups.
5. Go to the provisioning Overview and click Start provisioning. Entra then sends changes roughly every 40 minutes. The first cycle can take longer when there are many employees.

Under Settings, keep the Scope on Sync only assigned users and groups. Otherwise Entra sends your entire organisation.

Roles

The role in 2LRN4 comes from the app role you assign in Entra. You choose the names of those app roles yourself, in any language; in the portal you link them to the roles below under Role rules. With every change, 2LRN4 determines the role again. So if you change the app role in Entra, the role in 2LRN4 changes with it. A role you change by hand in 2LRN4 does not stick while SCIM manages the employee.

Fixed values. If you don't want to set role rules, give your app roles one of these values. 2LRN4 always recognises them, in every organisation: 2LRN4.Admin (customer administrator), 2LRN4.Manager (manager), 2LRN4.Communication (communication), 2LRN4.Helpdesk (helpdesk) and 2LRN4.User (learner). Upper and lower case don't matter. If someone has more than one, the first in this list applies. Role rules in the portal take precedence.

• Through SCIM, only roles within your own organisation are possible: learner, manager, customer administrator, communication and helpdesk. Roles of 2LRN4 or of a partner cannot be assigned through SCIM.
• Anyone without an app role, or with an app role that has no role rule, gets the default role, usually learner.
• With Entra ID P1 you can also link roles to groups. In that case, create a role rule in the portal with source Group and the group name.

A learner counts towards your number of licences. When your licence is full, 2LRN4 refuses new active learners until there is room again. Administrators and managers don't count.

Signing in

Employees created through SCIM sign in with their Microsoft account. See Sign in with your organisation account (SSO). Whether they receive a welcome email, you set yourself on the SCIM page in the portal. The usual messages about courses are sent as for any new user.

Troubleshooting

In Provisioning logs, Entra shows per employee what happened. The most common messages:

• Test Connection fails. Check that the tenant URL matches exactly the one in the portal, and that the token was copied in full. If in doubt, create a new token. If it still doesn't work, check that the SCIM connection is switched on in the portal.
• The email domain does not belong to this organisation. The address is outside the domains set up for your organisation.
• An account with this email address already exists. The address is already in use in 2LRN4 outside your organisation. Please contact us and we will find out who it belongs to. An account that was already in your own organisation is simply taken over by SCIM.
• This organisation's licence is full. There is no room for another active learner. Disable leavers or extend your licence.
• Too many deactivations in a short time. When many leavers come in within an hour, 2LRN4 holds them back until we have checked them. That way a mistake, such as an emptied group, cannot disable everyone at once. If the departures are correct, please contact us. Once we release them, Entra processes the changes automatically in the next cycle.

If you get stuck, email support@2lrn4.com. Include the name of your organisation and the time of the message. We can see in the connection's log what came in.