Using OAuth 2 authorization with Watershed

Watershed supports using both Basic HTTP or OAuth for authorizing xAPI activity providers, importing statements from another LRS and making API requests. This guide explains how to implement and this authorization method.

 Please note: Watershed only supports OAuth 2.0 Client Credentials Grant, otherwise known as OAuth 2 Two Legged auth flow as described in the OAuth 2 specification

Who can use this feature?
 User Roles
Global Admins can use this feature.
 Pricing 
Available on all plans (Essentials, and Enterprise).
 Expertise
Experts can use this feature.

Activity providers and OAuth

Start by configuring a new Activity Provider in Watershed. Don't forget to give the Activity Provider a memorable name like. Adding an Activity Provider will give you credentials to use for basic authentication, an endpoint url, key and secret which will look something like:

Endpoint https://watershedlrs.com/api/organizations/1234/lrs/
Key 30db41b72cbffb
Secret eb510b89c18441

OAuth and Tenant Server URLs

The OAuth and Tenant Server URLs are both based on the start of the Watershed Endpoint but have slightly different endings.  

If your Watershed Endpoint is

https://watershedlrs.com/api/organizations/1234/lrs/

then your OAuth Server URL removes the 'lrs' and adds 'oauth2/token' to become

https://watershedlrs.com/api/organizations/1234/oauth2/token

and your Tenant Server URL adds 'statements' to become

https://watershedlrs.com/api/organizations/1234/lrs/statements

Client ID and Secret

The OAuth Client ID and Client Secret are just the Key and Secret from the activity provider, with the Key being the Client ID and the Secret being the Client Secret.

Final configuration

Based on the example activity provider above the full OAuth credentials for the Activity Provider would be:

OAuth Server URL https://watershedlrs.com/api/organizations/1234/oauth2/token
Tenant Server URL https://watershedlrs.com/api/organizations/1234/lrs/statements
Client ID 30db41b72cbffb
Client Secret eb510b89c18441

Inbound LRS data and OAuth

Go to the Data page. In the menu on the left, click xAPI Data Sources. Inbound LRS Data is the 2nd section down: 

  1. Go to the Inbound Data section and click the and the Add Inbound Data Source button:Screenshot_2020-02-17_at_12_39_50_arrow.png
  2. Using data from the outside LRS, fill out the fields. Different LRSs call these different things:
    • Name: Name this something that will help you remember what it is.
    • Endpoint: Paste in the endpoint URL from the LRS that you’d like to pull statements from.
    • Key: Paste in the key, username or client ID from the LRS that you’d like to pull statements from. Please note: this is probably not the username you use to log in to the LRS.
    • Secret: Paste in the secret, password, or client secret from the LRS that you’d like to pull statements from. Please note: this is probably not the password you use to log in to the LRS.
    • OAuth: Paste in the URL of the Oauth token provider of the LRS you are connecting to. 
    • Last timestamp: select a timestamp that you want to pull statements after that time. 
  3. Click the Save button. All old statements from the other LRS should show up in your Data Search and so should any future statements made in the other LRS. If you don’t see any imported statements within 15 minutes, you should check your configuration and make sure everything was entered correctly.

Authorizing Watershed API requests with OAuth

This section describes how to utilise OAuth when making a Watershed API request, or when configuring a custom application or activity provider.

Client Credentials Grant

To use OAuth 2.0 authentication, the application sending xAPI data to Watershed first requests a time and scope limited bearer access token, and then uses that bearer access token to authenticate with Watershed's xAPI (and API) endpoints.

Request URL: /api/organizations/[org-id]/oauth2/token
Method: POST
Expected response code: 200 OK

Request headers

Header

Details

Content-Type

The content type for this request is application/x-www-form-urlencoded.

Please note: Authorization and X-Experience-API-Version headers are not used with this request.

Request Form Fields

The following form fields are used:

Field

Description

Required

grant_type

The grant type parameter should always have a value of client_credentials.

Required 

client_id

The activity provider key.

Required

client_secret

The activity provider secret.

Required

scope

Comma separated list of scopes e.g. xapi:read, xapi:write,xapi:all,wsapi:all. See below for an explanation of scopes. If not specified, defaults to whatever scopes have been granted to the activity provider credentials passed in the client_id and client_secret parameters.

Optional

expire_seconds

Number of seconds after which the bearer access token will expire. Defaults to 1 hour (3600 seconds). 

 Optional

Please note: the expire_seconds field is not part of the OAuth 2.0 specification, but is an additional property supported by Watershed so that clients can specify the expiry time.

Response

A successful response will return 200 OK and a JSON object with the following properties:

Field

Description

access_token

The token to use for authorization when making xAPI requests. 

token_type

This will always be bearer.

expires_in

Number of seconds after which the bearer access token will expire.

Scopes

The following scopes are supported:

Scope

Description

xapi:read

Permitted to make GET and HEAD requests to xAPI endpoints that support these methods.  

xapi:write

Permitted to make PUT, POST and DELETE requests to xAPI endpoints that support these methods.

xapi:all

Permitted to make any xAPI request. 

wsapi:all

Permitted to make requests to Watershed's API as a global admin user.

Please note: Activity Provider credentials cannot be used to create bearer access tokens with greater permission scope than they are granted. Requests for tokens will not fail in this scenario, but the resulting bearer access token will be restricted to the permissions of the Activity Provider credentials used to create it.

Using Bearer Access Tokens in xAPI Requests

 The bearer access token returned by the client credentials grant request can be used to authorize xAPI (and Watershed API) requests. For these requests, the authorization header should take the format:

Authorization: Bearer <access_token>

For example:

Authorization: Bearer ap_session_YXBfc2Vzc2lvbl9mMDhiOWEyNDAzYWI6ZDBlOWUxMTkxZTM5

Please note: Once the access token expires, it cannot be used for authentication and a new token must be requested.

Was this article helpful?
0 out of 0 found this helpful

If you can't find what you need or you want to ask a real person a question, please contact customer support.