Configure SCIM Provisioning With Udemy’s SCIM API

Overview

System for Cross-Domain Identity Management (SCIM) is a standard API for automating user and group provisioning/deprovisioning, and updating user and group data from the customer’s Identity Provider (IdP) into the Udemy Business account.  SCIM is supported by a number of Identity Providers such as Okta, Azure AD, and OneLogin.  You can also utilize the Udemy Business SCIM API for other IdPs or home-grown tools.

If your organization uses one of the following IdPs, please instead refer to our guides below for configuring SCIM:

SCIM uses a standardized REST API with data formatted in JSON. Udemy Business supports version 2.0 of the SCIM standard. The API is available for all customers that are on the Enterprise plan.

Udemy Business SCIM API supports the following features: 

  • Provisioning users
  • Deprovisioning users (deactivation)
  • Changing email addresses
  • Changing user details
  • Provisioning groups
  • Adding/removing users to groups

SCIM protocol description

SCIM Protocol is an application-level REST protocol for provisioning and managing identity data on the web. The protocol is client-server where the client is the Identity Provider (IdP) and the server is Udemy Business.

The basic flow is:

  • When access to Udemy Business is granted to the user in the IDP by the customer, the IdP sends us a request to check if the specific user exists in our database. They issue a User search request by an attribute like userName or email.
  • If the user does not exist, the IdP sends a request to create a user.
  • If the user exists, the IdP sends an update request for the user.
  • When access to Udemy Business is revoked, the IdP sends us a request to deactivate the user from our database.
  • IdP can also send requests to change user details.

How to access the API?

In order to obtain the authorization credentials to connect to the SCIM API, you will have to set up SCIM integration via Manage -> Settings -> Provisioning (SCIM) page in your Udemy Business account. Note that only Admins have access to this page. 

Click Start Setup.

provisioning_scim.png

In the next step, select Choose provider, then Custom.

select_provider.png

Click Generate token.

generate_token.png

On this screen, click Copy to copy the Bearer token to the clipboard.

copy_bearer_token.png

 

You will need to include Authorization HTTP header with the Bearer token in your requests, for example:

GET /scim/v2/Users HTTP/1.1

 Host: myorganization.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <enter you Bearer token here>

Content-Type: application/scim+json

Udemy Business SCIM API uses the HTTP protocol and is only available over a secure HTTPS connection.

The base URL for the API is https://<organization>.udemy.com/scim/v2/. 

If you are developing an application to interact with the Udemy Business SCIM API, it is recommended to refer to the SCIM RFCs included at the end of this document. Udemy Business SCIM API implementation is compliant with the standard.

SCIM API Endpoints

Informational Endpoints

These endpoints are information and serve to configure the clients. They do not require authentication, so you don’t need to include the Authorization header when accessing these endpoints.

GET /ServiceProviderConfig

Returns details about Udemy Business SCIM implementation including which methods are supported.

GET /Schemas

Returns information about the schemas that our SCIM implementation supports. Supported schemas are Users and Groups.

GET /Schemas/Users

Returns all attributes that we support for User resources.

GET /Schemas/Groups

Returns all attributes that we support for Group resources.

User Endpoints

Using these endpoints you can list users, filter by attributes, add new users, update  users’ information, or deactivate/anonymize users. Bear in mind that you will only be able to access users that were created using the SCIM API, users created within Udemy Business will not be available unless you reconcile them through SCIM. More details about reconciliation are given below.

Supported Attributes

SCIM attribute

Required?

Description

userName

Yes

The userName from the IdP. Must be unique.

name, { givenName, familyName }

No

Given name and family name of the user. Even though they are not required, we recommend always specifying those attributes since it’ll make it easier to identify users.

emails[type=”work”]]['value’]

Yes

Email of the user, must be unique

active

Yes

Flag to deactivate/reactivate users

title

No

User’s job title, i.e. “Senior Engineer”

externalId

Yes

The externalId of the user from IdP. Must be unique.

Please note: If you specify any other attribute that is not on this list, it will be ignored.

GET /Users

Returns a paginated list of users, 12 users per page by default. You can pass in count and startIndex parameters to paginate through the result set. For example:

GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

 Host: myorganization.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <enter you Bearer token here>

  • startIndex is the 1-based index of the first result in the current set of list results (offset)
  • count is the number of resources returned in a list response page (limit). You can retrieve no more than 1000 users in a single request. If this item is omitted it will default to 12.

GET /Users?filter=

This endpoint is used to filter users by specific attributes. For example, it is possible to search by userName attribute:

GET /Users?filter=userName eq "gloria.graynor”

Note: In the example above, you will need to urlencode the URL parameters so the URL becomes:
GET /Users?filter=userName%20eq%20%22gloria.graynor%22

This will return a list of user resources. If there are no results, an empty list will be returned.

The supported filters are:

  • userName
  • externalID
  • emails[type eq=”work”]

The supported operators are:

  • and
  • eq

Response:

  • HTTP status code 200 with the list of entities on success
  • HTTP status code 501 if an unsupported filter is supplied

POST /Users

This endpoint is used to create (provision) new users in Udemy Business. 

The response will contain an id attribute which should be used when referring to this user in all subsequent requests.

Note that:

  • New users created this way will not consume a license until that user signs in for the first time.
  • If there was an existing pending invitation for this user, it will get used at this point.
    The user will get added to groups, be assigned appropriate role/course assignments according to what is specified in the invitation.
  • An attempt to create a user that already exists in Udemy Business will cause the user to become SCIM managed (displayed with a small link icon in Manage Users pages). Note that user’s status and license usage will not be changed. If the user was active it will remain active and if the user was deactivated it will remain deactivated.

Response:

  • HTTP status code 201 and the user’s resource on success
  • HTTP status code 409 if the member with the same userName already exists in the Organization
  • HTTP status code 400 with the error details in the response body if the request did not pass validation

GET /Users/<id>

This endpoint is used to retrieve user details for a specified user. id parameter in the request above is a unique identifier that was returned when the user was created using SCIM or when listing all existing users.

Response:

  • HTTP status code 200 with the user resource on success
  • HTTP status code 404 if the user has not been found

PUT /Users/<id>

This endpoint is used to replace (overwrite) user details in Udemy Business. If specified, attribute active can be used to deactivate or reactivate the user.

Response:

  • HTTP status code 200 and the updated user resource
  • HTTP status code 404 if the user doesn’t exist. 
  • HTTP status code 400 in case of an attempt to deactivate an organization owner.

PATCH /Users/<id>

This endpoint is used to make partial updates to the user details in our system, meaning that you can use it to change only some attributes of the user. This is in contrast to PUT which replaces the entire user. 

It can contain attribute active which will cause the user to be deactivated or reactivated.

  • The body of each request MUST contain the "schemas" attribute with the URI value of "urn:ietf:params:scim:api:messages:2.0:PatchOp".
  • The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more PATCH operations.  Each PATCH operation object MUST have exactly one "op" member, whose value indicates the operation to perform and MAY be one of "add", "remove", or "replace".
  • The “path” attribute can be empty, in this case “value” should be a dictionary in the format of {“path”: “value”}.

Response:

  • HTTP status code 200 with the updated user’s resource on success
  • HTTP status code 404 if the user was not found
  • HTTP status code 400 if attempting to deactivate an organization owner or in case of an invalid operation.

Group Endpoints

Supported Attributes

SCIM attribute

Required?

Description

displayName

Yes

Group title. Must be unique among all Udemy Business groups.

externalId

No

The externalId of the group from the Identity Provider

Note: If you specify any other attribute that is not on this list, it will be ignored.

GET /Groups

This endpoint is used to get a paginated list of all provisioned groups. Include startIndex and count query string parameters to paginate through the results. 

Bear in mind that only groups created using SCIM will be returned. Groups created from Udemy Business will not be returned.

GET /Groups?filter=

This endpoint is used to filter groups by specific attributes. For example, it is possible to search by displayName attribute:

GET /Groups?filter=displayName eq "Marketing”

This will return a list of group resources. If there are no results, an empty list will be returned.

Note that you will need to url encode the parameters, so the request becomes:
GET /Groups?filter=displayName%20eq%20%22Marketing%22

The supported filters are:

  • displayName
  • externalId
  • Id
  • member.value

The supported operators are:

  • and
  • eq

Response:

  • HTTP status code 200 with the list of entities on success
  • HTTP status code 501 if the non-supported filter is used

POST /Groups

This endpoint is used to create (provision) new groups in Udemy Business. 

Response:

  • HTTP status code 409 If the provisioned group with the same name already exists in the org, we return 409 (Conflict) with a scimType error code of uniqueness.
  • When the group has been created successfully, we return the full representation of the group with HTTP status code 201 (Created) together with the Location header that contains the URL of the create group resource.

GET /Groups/<id>

This endpoint is used to fetch the group details from Udemy Business. 

Response:

  • HTTP status code 200 and a group resource
  • HTTP status code 404 if the group has not been found

PUT /Groups/<id>

This endpoint is used to replace the group details in Udemy Business.

Response:

  • HTTP status code 200 and the updated group resource 
  • HTTP status code 404 if the group doesn’t exist. 

PATCH /Groups/<id>

This endpoint is used to make partial updates to group details in Udemy Business. 

The PATCH endpoint is more tricky than others, as it supports different kinds of operations (and their combinations are possible):

  • replace operation changes the specified value. In our case it’s either group name or members.
  • remove operation removes a member from the group.
  • add operation adds members to the group.

The rules are the following:

  • We never remove unprovisioned members from the group (in case of `replace` members operation, for example).
  • PATCH request, regardless of the number of operations, SHALL be treated as atomic.

The input validations are the following:

  • The body of each request MUST contain the "schemas" attribute with the URI value of "urn:ietf:params:scim:api:messages:2.0:PatchOp".
  • The body of an HTTP PATCH request MUST contain the attribute "Operations", whose value is an array of one or more PATCH operations.  Each PATCH operation object MUST have exactly one "op" member, whose value indicates the operation to perform and MAY be one of "add", "remove", or "replace".
  • The “path” attribute can be empty, in this case “value” should be a dictionary in the format of {“path”: “value”}.
  • For “Remove” operation the “members” path is required.
  • For the “Add” operation either “members” or “externalId” “path” should be present.
  • For “Replace” operation “members” path may be present. If it’s not there it means that we are replacing the group details (like group name) but not members.

Note:

  • Assigning/unassigning users to a group happens asynchronously, so the changes won’t be reflected immediately in Udemy Business.
  • We do not support nested groups, so they will be ignored during this request.

Response:

  • HTTP status code 204 if the operation was successful.
  • HTTP status code 404 if the group does not exist.
  • HTTP status code 404 with the error details if there is an attempt to assign a group to a user that’s not a member of the organization.
  • HTTP status code 400 with the error details in the response body if the request did not pass the validation

DELETE /Groups/<id>

This endpoint is used to remove or deprovision a group in Udemy Business. 

The rules are the following:

  • If the group contains non-provisioned members, remove provisioned users from the group, delete `OrganizationSCIMGroup` record.

Response:

  • HTTP status code 204 if the operation was successful.
  • HTTP status code 404 if the group does not exist.

Further Reading

Related articles

Contact Us