Drillster Support & Info

Creating a typical LMS integration

The flow described here relies on the ability to keep the administrative OAuth token (and associated client secret) a secret from the end user. This means that a server side component is required, and that for instance a pure Javascript implementation that runs inside the learner's browser cannot be made to function securely.

A typical integration consists of a couple of components:

The aim of this document is to provide guidelines and best practices for making such an LMS integration. It is by no means an exhaustive description of what sort of integrations are possible. Also, this document assumes that the actual drill content will be created in Drillster by administrators of the LMS. There are ways to automate the loading of drill content, but that is beyond the scope of this document.

Connecting to the Drillster API

In order to create user accounts in Drillster, facilitate a seamless login or to retrieve proficiencies, an API connection between the LMS and Drillster must be created.

Drillster has a REST API that uses JSON as the data protocol. Requests to the API are authorized using the OAuth 2.0 mechanism. The use of OAuth means that API requests can be made on behalf of a Drillster user account as and when that user has given permission to the LMS to access the account.

In a typical LMS integration, the API requests are usually not directed at the individual user accounts, but rather at an administrative account in Drillster. This greatly simplifies things, as only a single account authorization is required.

To perform API requests on behalf of a specific user, please refer to the OAuth 2.0 documentation.

Back to top

Automatically setting up user accounts

Drillster is all about long term retention of knowledge. This means that it is imperative to track individual user progress, and in order to do that, a user account must exist in Drillster for each LMS user that needs to make use of Drillster functionality.

To set up a user account, just two things are required:

  1. The user's real name
  2. The user's email address or a previously agreed third party ID

Drillster does not use the email address as the primary key for the account, but assigns a unique alphanumeric user ID to each account. This user ID is returned in the response of the API call. It is entirely possible that the user changes her email address in Drillster, or adds additional email addresses to the account. Even the name can be changed by the user, but the user ID will remain constant.

Another possibility is that the user already exists in Drillster. The user could have a pre-existing account, or the LMS may not have recorded that it set up the account earlier. This is no problem, but it is important that the LMS deals with exception correctly.

Assuming that a valid OAuth token is available, the LMS can set up a new user by sending a POST request to https://www.drillster.com/api/2/users with parameters containing the details for the new user. For example:

POST https://www.drillster.com/api/2/users
emailAddress=jane.doe%40example.com&name=Jane%20Doe

It is possible to specify additional details of the account. Please refer to the API documentation for more information.

A successful response would have an HTTP response code 200 and returns the generated user ID as follows:

{
  "type": "USER",
  "id": "7qr6JFBZR27rLMXiqX0srg"
}

If the user already exists, an error response is returned with HTTP response code 400 (Bad request). The response does contain the user ID:

{
  "id": "account_exists",
  "description": "The identity \"jane.doe@example.com\" is linked to an existing account",
  "userId":"7qr6JFBZR27rLMXiqX0srg"
}

It is important to pick up the user ID in either case, as it is required in order to add this user to the appropriate groups.

For exact details about this API endpoint, please see the specification of the API's user endpoint.

Back to top

Automatically adding users to groups in Drillster

Drillster's groups provide a mechanism to allow access to predefined sets of drills or tests to a group of users. A group in Drillster in its simplest form is a collection of drills assigned to a collection of users. Once learning material is structured in groups, it becomes possible to set learning objectives, assign tests and to run various reports. Drillster's groups mechanism lends itself extremely well for integration with an LMS.

For the scope of this document it is assumed that the groups have already been created and filled with content (i.e. the drills or tests). Groups can be created in Drillster by the administrative user. It is also assumed that the LMS has knowledge of the group codes (unique IDs for each group) relevant for each user. This should probably be part of the course building process where a Drillster learning activity is included in the LMS.

In order to add a user to a group, the following information is required:

  • The group code. Group codes can be obtained from the Drillster website, where groups are created and managed.
  • The user ID. This is the ID that was obtained from the POST user API call.

The user is added to the group as follows:

PUT https://www.drillster.com/api/2/group/{group_code}/members/{user_id}

Or, with some example codes:

PUT https://www.drillster.com/api/2/group/0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI/members/7qr6JFBZR27rLMXiqX0srg

A successful response would have an HTTP response code 200 and returns a message stating that:

{
  "description": "The user has been invited to the group."
}

If the user was already part of the group, an HTTP response code 400 will be returned, with the following message:

{
  "id":"already_invited",
  "description":"A user with user ID7qr6JFBZR27rLMXiqX0srg is already invited to group0kIpT-yh7l6dF0w4EWkRYaB-0wzeHAJzM6vlL1te6wI"
}

Note that it is important to separate this error from other errors, as it still signifies a positive result!

By adding the user to the group, the user now has access to all of the drills and tests contained in the group. Should the user log in into the Drillster website, he or she will see all of the drills from the group listed in the repertoire. These drills do not count toward the storage limit of a basic user account. Any drills that are added to the group later will immediately be available to all current group members.

It is possible to remove users from a group through the API as well, but that is beyond the scope of this document. For exact details about this API endpoint, please see the specification of the API's group/…/members endpoint.

Back to top

Single sign-on

The next step in the integration is to provide a seamless experience for the user. If users are presented with a player widget in the LMS, Drillster does not know who that user is, unless they have logged in before. This means that Drillster will ask the user to log in, which is far from a seamless user experience. In fact, for users that have just been added through the API, there is no password set, so users are unable to log in until they configure a password.

To overcome this, Drillster supports single sign-on. There are two ways to use single sign-on (SSO):

  1. SSO through delegated login
  2. SSO through an OAuth 2.0 or OpenID Connect identity service

Delegated login

Delegated user logins provide a way for a third party to integrate Drillster into another product by way of automatically establishing a logged in user session on Drillster. That way users authenticated on the LMS do not have to log in into Drillster.

From a high level, the mechanism works as follows:

  1. The LMS system sends a delegated login request for a given user ID to the Drillster API.

  2. Drillster checks that the user making the delegated login request has the permission to let the requested user in into Drillster. In practice this means that the requested user must be member of a group for which the calling user has administrative rights.

  3. If permissions are OK, Drillster will respond with a message containing a unique access token. The token is only valid for a short time.

An access token can be retrieved by having the LMS make the following GET request:

GET https://www.drillster.com/api/2/access/{user-id}

Or, with some example data:

GET https://www.drillster.com/api/2/access/7qr6JFBZR27rLMXiqX0srg

An example of a typical response:

{
    "token": "eyJhbGciOiJSUzI1NiIsInR5...<truncated>"
}

The token should be picked up from the response message, and used as a drl-token attribute in loading the Drillster player widget or other widgets (see next section).

For exact details about this API endpoint, please see the specification of the API's access endpoint.

Back to top

OAuth 2.0 or OpenID Connect identity service

If you are using an identity service yourself to authenticate your own users, you can use it to perform SSO on the Drillster platform. The requirement is that your identity server is OAuth 2.0-compliant, and can be used by external parties like Drillster. 

For some well-known cloud-based identity services such as Microsoft Azure AD, Drillster has full support.

Even better is if your identity server complies to the OpenID Connect standard. This is a standard on top of OAuth 2.0, and makes it even easier to connect Drillster and your LMS, because it standardizes the way that the user information is retrieved.

The process works like this:

  1. The user logs in to the LMS, using the LMS identity service
  2. The user is sent to Drillster to practice a drill
  3. The user is not logged in to Drillster yet, so he is sent to the LMS's identity service
  4. After verifying that the user was already logged in to the LMS, he is immediately sent back to Drillster, with an authorization code
  5. Drillster uses the authorization code to request the user's details (e.g. email and name) from the LMS's identity service
  6. Drillster logs the user in, and allows the user to practice the drill

Please ask our support desk if you would like to use your OAuth 2.0 identity service to perform SSO for your users.

Which SSO method to use?

If you are already using an OAuth 2.0 or OpenID Connect identity service, it is strongly recommended to use it for SSO with Drillster. It provides the highest level of security, because it authenticates the end-user.

Delegated login can be used if you don't have such an identity service. Delegated login is simple to implement, but provides a security level that is not as high as an identity service. 

Back to top

Presenting drills to your users

Once a user ID has been established, the user is part of one or multiple groups, and an access token has been generated, it is time for some user interaction. You can display any test or drill widget to your users by embedding the Drillster player on the page. Please see our widgets documentation for details on how to display Drillster widgets on your page, and how to include the session token.

For the scope of this document, it is assumed that the LMS has knowledge of the drill codes that are part of the group. The only variable part in the embed code is the drill code, so the URLs are easy to generate.

A typical embed code for a player widget looks like this:

<script src="https://www.drillster.com/widgets/loader.js" type="text/javascript"></script>
<div class="drl-widget drl-player" drl-code="CZ_nPz74RJ2zFotkYzaUJw" drl-token="l1ko49urumvkgnZ8"></div>

Again, please refer to our widgets documentation for details about the use of the widget loader and customization options.

If you are unable or unwilling to store the user ID beforehand, it is possbile to execute the three steps described above in rapid succession as and when you are looking to present a test or drill widget to a user. This means: ① create the user (or determine the user ID from the response if the user is already present), ② add the user to the group, ③ request an access token, ④ present a test or drill widget to the user with the token included.

The player widget is able to open tests as well as drills. Embedding these works in exactly the same way. The test keys can be extracted from the group detail screen in the Drillster application. The test key is the same for each group member.

Back to top

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.