OAuth 2.0

Drillster uses the 🔗 OAuth 2.0 protocol for authentication and authorization. This guide assumes you have a basic understanding of the OAuth 2.0 protocol.

Scenarios

There are two scenarios that require you to obtain an access token from the Drillster OAuth 2.0 authorization server.

1. Access organization resources through API
   You want to access your organization's resources through the Drillster RESTful API. These resources can be your organization's accounts, groups, catalogs, objectives, results and more. The access token must be sent with each API call.

2. Embed a widget in your website
   You want to embed a Drillster widget, such as the Player, into your website. Your end user is automatically logged in, and can immediately use the widget. The access token must be used to start the widget.

The difference between the two scenarios is the owner of the resources being accessed: ① your organization, or ② your end user. An access token is always obtained for a single Drillster account. For the embedded widget scenario, this is your end user's account. For the API scenario, this is an account that is managed by your organization, and has sufficient privileges to perform the API calls. Drillster uses service accounts for this.

Service accounts

Service accounts are accounts that can only be used for server-to-server communication. You use them to call the Drillster RESTful API from your server application. For security reasons, service accounts must never be used in browser applications (Javascript) or mobile applications.

Consult the service accounts documentation to learn how to create service accounts for your organization.

JWT Authorization Grant

For both scenarios, the access token is obtained by using a JWT Authorization Grant. This is an extension of OAuth 2.0, and is defined in JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (🔗 RFC-7523 2.1).

This grant type is different from the common 🔗 Authorization Code Grant, and doesn't involve redirecting the user to ask for approval. The reason that this is not necessary is that there is a trust relationship between the OAuth client (your integration with Drillster) and the resource owner (your service account on behalf of your organization, or your end user). The JWT used in this grant type expresses this trust relationship.

See JWT Authorization Grant for details on how to implement this in your server application.

Using the access token in your API calls

To use the Drillster RESTful API with the access token you obtained, you need to include it in every API request you submit. The access token must be submitted in the HTTP Authorization header, as a bearer token. The value of the Authorization header must be Bearer {access token}.

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJXSHJrck9DMFNEcWY2VjNXYVRrblpRIiwiZXhwIjoxNDYzMDY1MDkyLCJhdXRob3JpdGllcyI6WyJST0xFX1VTRVIiXSwianRpIjoiZDMyNDQ1YzEtMDAxYi00ZTkyLTgxOWMtOGUxZDcyMGQ1N2RmIiwiY2xpZW50X2lkIjoiZGNlOWM0ZDFiMTZkNGRjOGIzNDI4NjlhM2ZlNTliYjkiLCJzY29wZSI6WyJST0xFX1VTRVIiXX0.QknsrlC7BFYukHCsFhL-XGT10j8dpOcjX1yB4_bOz9k

Access token expiration

All access tokens issued by the Drillster Platform can only be used for a limited amount of time, after which they expire. This duration varies, but typically ranges from one to several hours. No refresh tokens are issued, so your client application must request a new token when the previous one is expired, using the JWT Authorization Grant.

Using the access token in a widget

Most widgets (including the Player) support access token injection. The access token is injected into the widget using the drl-token attribute. For example:

<div class="drl-widget drl-player" drl-token="{access token}"></div>

See also the widget documentation for more detailed information on the use of our widgets.