All Collections
Learnerbly for Admins
Setting up Okta User Provisioning
Setting up Okta User Provisioning

How to set-up user provisioning for your users with Okta and via SCIM 2.0

Galina Grkovikj avatar
Written by Galina Grkovikj
Updated over a week ago

We assume that your organisation already have an Okta account and that your people's information has been onboarded onto this account. If you have not done so, please review Okta's Help Centre for more information.

If you would like to learn more about Single Sign On Okta, please read this article here.

Step 1: Add the Learnerbly App

Once you've logged into your organisation's Okta account, the first step is to add Learnerbly as a new application to Okta.

Click on ApplicationsApplicationsBrowse App Catalog

Search for Learnerbly in the search bar (make sure to spell our name correctly!)

Click on Add.

Make sure that our app is not be made visible to users or be displayed in the Okta Mobile App, as users will not be able to log into Learnerbly via this application.

Click Done.

Once the Learnerbly application is added, click on the Provisioning tab and then click Configure API integration.

Select Enable API integration where you will be able to enter API token.

Open a new window and go to LearnerblyAdminSettings.

Under API, click on Generate key to create the API token you will need.

Copy the API token in the subsequent pop-up window.

Insert the token into the previous Okta window where it says API Token in the following format:

Static <<API token>>

Click Test API Credentials. If the test passes, click Save.

Step 2: Map the user attributes

After saving, you will land on the following page. By default, the three functions to Create Users, Update User Attributes, and Deactivate Users are enabled.

If for any reason, you want to disable these functions you can click on Edit, and deselect the options of your choice (however, we highly recommend that you don't do this). Remember to click Save to apply the settings.

Next scroll down the page where you map the user fields from Okta to Learnerbly so we can sync the user information between the two systems.

Click on Go to Profile Editor and then Mappings and toggle to Okta User to Learnerbly.

Learnerbly defines the following custom SCIM attributes under the namespace urn:learnerbly:params:scim:schemas:2.0:User.

The following attributes are common and Okta automatically provides a mapping to them:

  • userName - automatically set by Learnerbly as a string

  • givenName - the first name of the user as a string

  • familyName - the last name of the user as a string

  • email - the email of the user

  • emailType - this defaults to work or null

  • locale - the default locale settings

The following attributes are Learnerbly specific and require attention:


approvers - an array of the user's approvers emails formatted as {string}

We suggest that you define a custom attribute approvers in Okta that you populate from your HRIS and map this to the approvers attribute in Learnerbly.

Content Regions

contentRegion - ISO 3166-1 alpha-2 country code as a string

The contentRegion input is re-mapped to a supported content region according to the following table:

Content Region

Country Codes

United Kingdom (GB)


Spain (ES)


Germany (DE)


United States (US)


Sweden (SE)


All other country codes are mapped to the Global content region, under the alpha-2 code QQ.

You should therefore expect that this value may be different from the one passed in from Okta.

If there is no country code set, it will automatically default to QQ.

The approvers and contentRegion fields are not mandatory however, we strongly recommend these fields are mapped to the relevant information to ensure the correct Learnerbly configuration is set up.

Custom Fields

Finally, if you want to map additional fields to Learnerbly, for example, if you want to add job function for additional reporting and analytics, you can do so with 3 custom fields:

  • customField1

  • customField2

  • customField3

Go to Profile Editor and then Add Attribute.

Complete the following fields:

  • Data type - select the appropriate type

  • Display name - name the field with the actual name of the attribute i.e. job function

  • Variable name - this should be either customField1, customField2 or customField3 in the following format learnerbly.customFieldX

  • External name - this should be either customField1, customField2 or customField3

  • External namespace - this is urn:learnerbly:params:scim:schemas:2.0:User

Please fill in the other fields as you see fit e.g. a description.

You can find more information about our SCIM 2.0 documentation here.

Step 3a: Assigning users for new customers

This step is for new customers being onboarded where they have users in Okta and they want to create the users in Learnerbly. Otherwise, proceed to Step 3b.

For new customers being onboarded, they will need to "assign" all of their users from Okta to Learnerbly i.e. create and link all the users in Learnerbly from Okta.

Go to the Assignment tab within the Learnerbly application, then Assign, then Assign to People.

Select the users you want to assign and click Assign.

You will get to a stage where you see the user information mapped to the fields.

For the following Learnerbly specific fields:

  • Content Region - please ensure this is mapped alpha-2 country code based on the user's country otherwise it will default to QQ.

  • Approvers - the approvers will be blank as the approver does not exist in Learnerbly yet. You will first need to create the users in Learnerbly and then apply a Sync.

When you are done with this click Save and Go Back.

Syncing is the process of syncing all the user information from Okta to Learnerbly.

After you created all the users in Learnerbly, you need to apply a Sync to ensure all the approver information is added.

Go to the Provisioning tab and scroll down to Learnerbly Attribute Mapping and click on Force Sync.

That's it! From this point onwards, Okta should automatically assign any new users to Learnerbly and users will be automatically created, updated and deactivated in Learnerbly.

Step 3b: Assigning users for existing customers

This step is for existing customers with users currently active on Learnerbly.

For existing customers, there will be existing users in both Learnerbly and Okta. Therefore, you will need to link the users between the two systems by matching them.

Go to the Import tab and click Import Now to import all the users from Learnerbly into Okta.

On the left hand side, you will see all the imported users from Learnerbly. Okta will now try to match each user with a user in Okta by looking at the email address. If there is no match, Okta will create a new user in Okta.

For all the successful pairings where a Learnerbly user matches with an Okta user, tick the box on the right-hand side of each row and clicking Confirm Assignment and then Confirm.

For the cases where there is no match, it is usually due to a mismatch in emails between Learnerbly and Okta. Since Okta is the source of truth, you should not be creating any new users in Okta. Instead, manually correct the email in Learnerbly before attempting the import and match stages again.

If there are any users in Learnerbly that you think needs to be synced again with the latest information, you can go to the Provisioning tab and scroll down to Learnerbly Attribute Mapping and click on Force Sync.

That's it! From this point onwards, Okta should automatically assign any new users to Learnerbly and users will be automatically created, updated and deactivated in Learnerbly.

Step 4: Creating and syncing groups

We need to ensure the groups created in Okta are synced to the groups in Learnerbly.

First, the groups must be created in Okta.

Click on DirectoryGroups.

The groups can be either synced up with your HRIS or you can add and manage your Groups here.

You can add groups by clicking on Add Group and following the on-screen instructions to create the group.

Then click on the newly created group and click Manage People.

Then you can add the relevant members to the group by clicking on the individual users or by clicking Add All.

With groups created in Okta, you need to sync them to Learnerbly.

Click on ApplicationsApplicationsLearnerbly.

Go to Push Groups tab and click Add Push Groups and then Find groups by name. You may have to click Refresh App Groups if you do not see the Groups.

Find the relevant group and under Match result & push action, either choose:

  • Create Group - if the Group does not exist in Learnerbly

  • Link Group - if the Group does exist in Learnerbly

Check the box Push group memberships immediately if you want the group to be pushed to Learnerbly immediately.

Click Save or Save & Add Another if you want to add another group.

There is more functionality around groups in Okta. For example, you can create different groups and assign them to different applications with specific rules that will allow you to tailor the setup to your specific needs. You can find out more here in the Okta documentation.

Step 5: Verify users in Learnerbly

The final step is to verify all the user information in Learnerbly is correct.

Log into Learnerbly as an admin.

Go to Admin and then People.

Check that all users from the previous steps have been added and are in sync.

Did this answer your question?