Articles in this section

See more

Portal: set up SCIM 2.0 with bearer-token authentication

Elizabeth
  • Updated

Set up an IdP with OAuth 2.0 to create and manage accounts

Use SCIM 2.0 protocol with your identity provider (IdP) to create, read, update and deactivate accounts in LearnUpon.

For customers using an IdP with bearer/token authentication, SCIM (System for Cross-domain Identity Management) makes managing user identities in LearnUpon easier.

For basic authentication, see Portal: set up SCIM 2.0 with basic authentication.

Availability: depends on your LearnUpon plan

SCIM 2.0 overview

The SCIM protocol is an application-level REST protocol for provisioning and managing identity data on the web. The protocol supports creation, discovery, retrieval, and modification of core identity resources.

LearnUpon lets you set up an identity provider that uses SCIM 2.0 to create, read, update and deactivate accounts from a single source.

Currently, this provisioning works in one direction. You create or update accounts in the identity provider, and SCIM creates or updates the same details for a new account in LearnUpon.

You can't create new accounts in LearnUpon and export them to your identity provider.

Note: LearnUpon supports long-lasting access tokens, valid for up to 1 year. These long-lasting tokens are required for custom integrations with IdPs like Microsoft Entra ID.

Background

LearnUpon is not responsible for content outside this site.

Prerequisites

For SCIM 2.0 using OAuth 2.0 your LearnUpon portal requires the following features turned on:

With these features in place, you set up an app for bearer/token authentication in your identity provider.

Review the documentation from your IdP so you understand its processes for setup.

Access permissions

  • admins with full portal permissions: can set up this feature

SCIM 2.0 is available for both top-level and sub-portals. You set up each portal individually as required.

Add SCIM provisioning

Follow the instructions from your identity provider for bearer/token authentication. 

Note: if your portal uses advanced passwords, you need to set up password synchronization in your identity provider.

See: Set advanced password requirements for the portal

Create an OAuth app in LearnUpon for connecting to your IdP

See Use OAuth 2.0 to connect applications to LearnUpon 

Look for the required Redirect URL in your IdP’s documentation, something similar to

https://system-admin.your_idp.com/admin/app/cpc/{appName}/oauth/callback, where {appName} is the name of your organization’s app in your IdP settings.

Required LearnUpon details for setup

  • SCIM connector base URL: https://yourportal.learnupon.com/api/v1/scim/
  • Unique identifier field for users: email or userName
  • Supported provisioning actions:
    • Import New Users and Profile Updates
    • Push New Users
    • Push Profile Updates
  • Authentication Mode: bearer/token, aka OAuth 2.0

If required: create a long-term bearer token

Some SCIM 2.0 providers, such as Microsoft Azure, require a long-term bearer token. You can create a token using an application such as Postman, terminal or similar software that can send and receive http requests.

Before starting, confirm you created your OAuth application in LearnUpon with a token expiry length of 1 Year.

The following instructions use Postman to provide an example.

  1. In Postman, create a new request.
  2. Go to Authorization.
  3. From Type, select OAuth 2.0.
  4. From Configure New Token, fill in the following options:
    • Grant Type: Authorization Code
    • Callback URL: Enter the Redirect URI you configured in LearnUpon
    • Auth URL: https://yourdomain.learnupon.com/oauth/authorize
    • Access Token URL: https://yourdomain.learnupon.com/oauth/token
    • Client ID: Use the Client ID generated from your LearnUpon OAuth 2.0 client
    • Client Secret: Use the Client Secret generated from your LearnUpon OAuth 2.0 client
    • Scope: full offline_access (or the specific scope you need)
    • Client Authentication: Send as Basic Auth header
  5. Select Get New Access Token to open a browser window, to the LearnUpon login page.
  6. Log in with your LearnUpon credentials.
  7. After successful authentication, LearnUpon redirects you to Postman with an authorization code. Postman automatically exchanges this code for an access token.
  8. Copy the Access Token for use in your SCIM Provisioning provider settings.

The following screenshot is an example of an access token generated through Postman.

sample postman bearer token for 1 year.png

Parameters available for update through SCIM 2.0

You can update the following parameters through SCIM. When you change them in your identity provider, the changes appear in LearnUpon:

  • first_name
  • last_name
  • username
  • email
  • login_enabled
  • portal_membership_type

Use default mappings first 

Most Identity Providers (like Okta or Azure AD) automatically map their internal attributes to LearnUpon’s parameters. For example, Okta usually maps name.givenName to LearnUpon's first_name by default. 

You only need to manually configure these if your IdP does not provide a default mapping.

Set up attribute mapping from your identity provider to LearnUpon

In your identity provider app, you need to specify what data you want the IdP to share with LearnUpon, and where map it to LearnUpon attributes, when creating or changing a user’s profile.

If your organization uses different userTypes, you can map them to one of the LearnUpon user types. For example, your organization can map director to the LearnUpon admin user type. Your identity provider will set up an admin account for every director in your organization.

Create detailed user profiles including custom user data

Beyond provisioning the basic parameters from your identity provider (IdP) by default, you can map custom attributes to LearnUpon’s custom user data fields. 

See Use default mappings first about default mappings.

Mapping custom attributes means you can create and maintain user accounts with custom user data automatically, as soon as you create the account in your IdP.

LearnUpon’s custom user data fields drive its dynamic rules and its learning journeys. Setting up accounts with custom attributes from your IdP mean you can build effective learning workflows, and get your learners started as quickly as possible.

See:

This procedure uses Okta as an example IdP. The same process is possible with other providers like Microsoft Entra ID (previously Microsoft Azure AD).

Prerequisites for custom attributes

To add custom attributes mapping you need:

  • SCIM 2.0 set up as your protocol for sharing identity data between systems
  • default SCIM mapping enabled in your IdP

Access permissions to set up custom attributes

  • admins with full portal permissions: can set up this feature

The admin requires permissions in the IdP to create custom attributes.

Map custom attributes in Okta to custom user data in LearnUpon

Warning: in your IdP, you must set the namespace field to urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.

This entry is the standard SCIM enterprise extension namespace that lets you map and synchronize custom attributes between your identity provider and LearnUpon.

In Okta: create a custom attribute in the Okta profile editor

  1. Within Okta, navigate to Profile Editor.
  2. Select the user profile related to your LearnUpon app.
  3. Select Add Attribute and configure the new attribute with the following required fields:
    • Display name: for example, New Custom Attribute Scim
    • Variable name: for example, newcustomattributescim
    • Namespace: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
    • Attribute type: Personal
  4. Save the attribute.

In Okta: map the attribute to your LearnUpon app

  1. Go to your LearnUpon application in Okta.
  2. Navigate to Provisioning > To App.
  3. Select Show Unmapped Attributes.
  4. Find your custom attribute in the list.
  5. Select your custom attribute > Map from Okta Profile.
  6. Select the Okta profile field to map to this attribute.
  7. Save the mapping.

In Okta: verify your attribute schema

Check your custom attribute schema. Look for the syntax format: namespace:attribute_variable_name. For example: 

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

In LearnUpon: add SCIM attributes

  1. From main navigation go to Settings > Integrations > SAML SSO.
  2. Select SCIM settings.
  3. From Custom user data mappings, enter the Variable name you set in your IdP for each custom user data field. For this example enter newcustomattributescim.
  4. Save to finish.

See:

 

Related articles