User Provisioning Overview with SCIM

Introduction

The System for Cross-domain Identity Management, or SCIM, is an API specification that was created to facilitate the management of people and groups of people in cloud-based applications and services.

OutThink’s SCIM API is built to be compliant with the SCIM 2.0 specification and can be integrated with major Identity Providers like Entra ID (Azure AD), Okta and OneLogin. The intention is to use our SCIM API to programmatically create and manage end-users within your organization(s).

OutThink’s SCIM API processes people (aka end-users, learners) and groups of people.

Basic API Information

The base address of OutThink’s SCIM API is as follows:

https://outthink-api.azure-api.net/scim/Organizations/{org_id}/v2

where {org_id} is the unique identifier assigned by OutThink to an organization within your corporate hierarchy. This may represent your entire company, or a specific sub-organization, division, or customer.

Unlike most other solution providers, OutThink supports multiple SCIM API integrations side-by-side, allowing you to automatically provision end-users and groups at different levels of your business operations independently.

Authentication

To use the SCIM API, you’ll need an access token (or secret token) for your organization. This token will be generated by OutThink upon request and provided securely to you alongside the organization identifier.

The token will grant administrative rights to manage end-users within the organization, including adding, editing and deleting. It is therefore important to ensure the token is managed securely and never stored in clear text.

Tokens may be regenerated at any time upon customer request.

Using the API

The API is accessed securely via HTTPS.

The Authorization header with the type of Bearer must be used passing the access token when calling any of the endpoints in the API (with the exception of the /ServiceProviderConfig endpoint).

Using the API is a matter of setting up your SCIM 2-compliant Identity Provider software to talk to the OutThink SCIM API. Read on for a fuller understanding of the OutThink SCIM API, and a link to instructions for setting up Azure Active Directory (Azure AD) and Okta specifically.

API Reference

Users

SCIM Users represent end-users in your OutThink organization. You can create, update, list, activate, deactivate and delete users within the organization via the SCIM API.

SCIM Attribute	Description	Required	Type
userName	Unique internal identifier of the user in the source system	Yes	string
active	Whether the user is in an active (enabled) state	No	boolean
externalId	External reference identifier of the user	No	string
name.givenName	User’s first (or given) name	Yes	string
name.familyName	User’s last name (or surname)	Yes	string
emails[type eq “work”].value	The user’s corporate email address	Yes	string
addresses[type eq “work”].country	The user’s country of residence or work	No	string
roles[primary eq true].value	The job title of the user	No	string
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department	The name of the department to which the user belongs	No	string
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:division	The name of the corporate division to which the user belongs	No	string
urn:ietf:params:scim:schemas:extension:enterprise:2.0:employeeNumber	The user’s unique identifier in the corporate LMS	No	string
nickName	The user’s unique name, badge Id, or other identifier, used for identification of the user, typically where email address is unavailable	No	string
preferredLanguage	The user’s preferred language	No	string

Note: Other attributes supported by the SCIM specification, if provided, won’t be synchronized between Identity Providers and OutThink.

Supported SCIM Schemas

OutThink uses the core SCIM schema, plus the Enterprise User extension schema. The latter is used to convey the following information for end-users (learners):-

• department
• division
• employeeNumber

(See the SCIM schema specification for full details of SCIM schemas.)

Supported Operations

• POST /Users 
  Creates a user.
  
• GET /Users/$userID
  Gets a single user.
  
• GET /Users
  Search for users with filtering, via GET.
  
• POST /Users/.search
  Search for users with filtering, via POST.
  
• PUT /Users/$userID
  Updates a single user (all attributes).
  
• PATCH /Users/$userID
  Updates a single user (add, replace, remove selected attributes).
  
• DELETE /Users/$userID
  Deletes a single user.
  
• GET /ServiceProviderConfig
  Gets service provider configuration.
  
• GET /Schemas
  Gets all supported schemas.
  
• GET /Schemas/$schemaID
  Gets a specific schema.

Example Request

The following is an example request received by the OutThink SCIM API for creating an end-user.

# Example request to create an end-user
POST https://outthink-api.azure-api.net/scim/Organizations/xxxxxxxxxxxxxx/v2/Users
Content-Type: application/scim+json
Authorization: Bearer xxxxxxxxxxxxxx

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "john.smith@outthink.io",
  "externalId": "81ef27b8-80ce-4c24-ba1e-067048806ecf",
  "active": true,
  "name": {
    "familyName": "John",
    "givenName": "Smith"
  },
  "emails": [
    {
      "value": "john.smith@outthink.io",
      "type": "work"
    },
    {
      "value": "mary.jones@outthink.io",
      "type": "other"
    }
  ],
  "addresses": [
    {
      "country": "GB",
      "type": "work"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "department": "Marketing",
    "division": "Southern",
    "employeeNumber": "12847A"
  },
  "roles": [
    {
      "value": "Marketing Assistant",
      "primary": true
    }
  ],
  "nickName": "A-12132",
  "preferredLanguage": "en-GB"
}

Line Managers

Due to some provider’s non-conformance to the SCIM specification, ingestion of end-user line managers (if required) should now be achieved via a GraphAPI integration.

Groups

SCIM Groups represent groups in your OutThink organization. You can create, update, list and delete groups within the organization via the SCIM API.

Note: Only users who are direct members of the specified groups will be ingested. The synchronization does not cascade to nested groups.

SCIM Attribute	Description	Required	Type
displayName	Unique name of group	Yes	string
externalId	External reference identifier of the group	No	string
members	The zero or more users who are members of the group. Each user is identified by their OutThink-assigned unique user id.	No	string

Supported Operations

• POST /Groups
  Creates a group.
  
• GET /Groups/$groupID
  Gets a single group.
  
• GET /Groups
  Search for groups with filtering, via GET.
  
• POST /Groups/.search
  Search for groups with filtering, via POST.
  
• PUT /Groups/$groupID
  Updates a single group (non-member attributes and members).
  
• PATCH /Groups/$groupID
  Updates a single group (add, replace, remove selected non-member attributes; add, remove members).
  
• DELETE /Groups/$groupID
  Deletes a single group.
  

Example Request

The following is an example request received by the OutThink SCIM API for creating a group.

# Example request to create a group
POST https://outthink-api.azure-api.net/scim/Organizations/xxxxxxxxxxxxxx/v2/Groups
Content-Type: application/scim+json
Authorization: Bearer xxxxxxxxxxxxxx

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "Marketing",
  "externalId": "81ef27b8-80ce-4c24-ba1e-067048806ecf",
  "members": [
    {
      "value": "e09df84b-4717-44bf-96ca-2cfa4e950b5b"
    },
    {
      "value": "b1952375-b78b-40bd-8848-80faab1452ae"
    }
  ]
}

SCIM Implementations

OutThink have provided documentation to assist you in setting up a SCIM integration with the following providers. For any provider not listed below, consult your product documentation.

Was this helpful?

YesNo

3 / 0