By Alex Bedley – September 1, 2016
Updated February 4th, 2021
Who are OAuth 2.0 refresh tokens for?
This article is of interest for developers creating applications that interact with Brightspace APIs on behalf of their users. This method of authentication is only recommended if your application is headless (not browser-based).
What is an OAuth 2.0 refresh token?
As part of good security practice, access tokens (tokens that allow you to authenticate with Brightspace APIs) expire after a short period of time. This creates a problem, as now applications will need a way to get new access tokens frequently. Refresh tokens solve this problem.
Refresh tokens are one-time use tokens that are issued to third party applications by the authorization service. The application stores this refresh token until the associated access token expires. Refresh tokens can then be traded in for a new access token and refresh token. Refresh tokens (and access tokens) should be treated like passwords.
How do I obtain an OAuth 2.0 refresh token?
The following sections will detail how to:
- Download the sample application which walks users through the OAuth 2.0 flow
- Register the application with Brightspace
- Obtain user consent to allow the sample application to access Brightspace APIs on behalf of the user
- Acquire a refresh token (and an access token) for that user
Download the sample application
The sample application, once registered, will allow you to work through the OAuth 2.0 flow in a user-friendly manner. It is useful for understanding how to obtain refresh tokens and can also be used when testing your applications. It is recommended to run the application locally.
Run locally
To run locally you must have <a href=" target="_blank">node</a> and npm installed.
- Clone the repo:
https://github.com/neverendingqs/oauth2-client-shell
- Install the dependencies:
npm install - Start the application:
npm run dev - Navigate to https://localhost:3001/
- Your browser might complain about SSL certificates at this point ("Your connection is not secure") because the application is using a self-signed certificate. In this case, since you are hosting it locally, we can safely ignore these warnings.
Registering the application with Brightspace
To perform the following steps, the reader must have admin access (or know someone with admin access) to their Brightspace instance.
- Navigate to Manage Extensibility in the Admin Tools menu.
- Click on the OAuth 2.0 tab.
- Click the Register an app button.
- Fill out the required details:
- To get the Redirect URI, look at the value of the Redirect URI field in the sample application UI. If you are hosting the sample application locally, Redirect URI should be https://localhost:3001/.
- For the Scope field, use
core:*:*. - Make sure Enable refresh tokens is checked on.
- Click the Register button.
- Obtain the Client ID and Client Secret for the app that you just registered.
Obtain user consent
Before you can obtain a refresh token for a user, that user must allow your application to access Brightspace APIs on their behalf.
- In the sample application fill in the following fields:
- Authorization Endpoint: https://auth.brightspace.com/oauth2/auth
- Client ID: Obtained in the Registering your application with Brightspace section above
- Scope:
core:*:*
- Click the Get Authorization Code button.
- The page will redirect you to sign into your Brightspace instance (if you aren't already signed in).
- Once you are signed in, click the Accept button.
- Brightspace should redirect you back to the sample application.
In this section, we obtained consent for a user and got an Authorization Code. We will need this Authorization Code to get a refresh token for the user.
Acquire a refresh token
Now that we have our Authorization Code we can trade this in for an access and refresh token. Continuing from the previous section:
The sample application should have automatically opened the Access (and Refresh) Token via Authorization Code section of the app and filled in the Authorization Code field.
Fill in the following fields:
- Client Secret: Obtained in the Registering your application with Brightspace section above
- Token Endpoint: https://auth.brightspace.com/core/connect/token
Figure: The OAuth Client Shell.
Click the Trade In Authorization Code button.
You have now successfully obtained a refresh token!
Where do we go from here?
This article showed you how to obtain a refresh token with the help of a sample application. In your production application, you will store this refresh token and associated access token securely. The access token allows you to access Brightspace APIs on behalf of a consented user.
Refresh tokens are long-lived, but one-use: you cannot re-use a refresh token to ask for a new access token. Instead, you use them once, and you should get back a new access token and a new refresh token (which you will use later for a subsequent refresh-token workflow).
App developers need to pay attention to the expiry times on tokens: access tokens have a short expiry time; refresh tokens have a long access time. In order to successfully use the refresh token workflow over and over to keep the app’s access fresh, they need to ensure they engage in that refresh workflow before the refresh token expires (each time they attempt to refresh).
Learning Extension: Access Free Course
Brightspace Clients can access a free course on getting started with the Brightspace API, in the Learning Center.
Access Course: Learn Postman With Paul
*Learning Center Access is provided to Instructors and Administrators who are currently using Brightspace. You must be signed into the Community with your School or Organization's email address to verify your access to freemium and premium Learning Center content.
Figure: OAuth2 sample application image.
Figure: An example of registering an application.
