Originally published February 20, 2019
D2L and Integration Standards
At D2L we have, and will continue to, be strong supporters of integration standards. In late 2016 we added OAuth 2.0 support for development of Brightspace API apps. OAuth 2.0 is an open standard authentication framework that provides multiple authentication flows, including the three-legged OAuth flow. It allows developers to write applications that access different services on behalf of a user.
Please note that we will continue to support our Id/Key Pair authentication model. But our focus is going to be towards continued support and growth of OAuth 2.0. An example of this is a recent update that we made to our OAuth 2.0 implementation. In our March 2019 product release, we now support using the Client_ID request parameter to identify itself when sending requests to the token endpoint. This might not sound like much, but we are hopeful that this update will be of benefit to many Brightspace developers.
Why did we perform this update?
The inclusion of the Client_ID value will not impact any existing OAuth 2.0 apps. So why did we do it? Well, other than being more adherent to the standard, through the Developer Community we heard from our customers that our OAuth 2.0 implementation was not compatible with some 3rd party API tools. Most specifically Brightspace developers were unable to use Postman with the Brightspace API as it included the Client_ID value in the request to perform an OAuth 2.0 based interaction.
What is Postman?
Postman is the market leading API test tool. It is available for free download at www.getpostman.com.
Postman is both powerful and easy to use and its Support Center is very helpful. Amongst its many features, we believe the following will be very helpful to Brightspace API developers:
- Create development Environments (e.g. one for your Brightspace Test site and one for your Production site)
- Create Environment Variables (e.g. Brightspace Domain, API Version)
- Create Collections which provide the ability to run multiple API calls in sequence
- Use JavaScript to pass variables into an API call
- Use JavaScript to store variables after an API call
Walkthrough - Brightspace OAuth 2.0 & Postman
Start with a Brightspace OAuth 2.0 App
Using Postman with Brightspace requires a Brightspace OAuth 2.0 app. If you don’t already have an OAuth 2.0 app you can either create one in your instance of Brightspace or use the public app provided in the Brightspace Development Environment (make sure you Join the Developer Group to access the “Developer Instance Credentials” file which contains the OAuth 2.0 public app details).
Creating a Postman Collection and connecting it to Brightspace
Prior to starting, make sure that you have installed Postman. Use the following steps to setup Postman authentication with your Brightspace app:
- Launch Postman
- You should be prompted with a Getting Started window. Under the default “Create New” select “Collection”.
- Specify a Name for your new collection (e.g. “Brightspace API Testing”).
- Select the Authorization tab.
- From the Type drop down select “OAuth 2.0”.
- For the Add auth data to drop down select “Request Headers”.
- Next click the Get New Access Token button.
- The Get New Access Token window will appear. You will need to configure each field of as follows:
- Provide a Token Name value (e.g. “Brightspace Dev Environment Token”).
- Grant Type set to Authorization Code.
- Callback URL should match the Redirect URI value from your Brightspace App.
- Set Auth URL to https://auth.brightspace.com/oauth2/auth
- Set Access Token URL to https://auth.brightspace.com/core/connect/token
- Client ID should match the Client Id value from your Brightspace App.
- Client Secret should match the Client Secret value from your Brightspace App.
- Scope should match the Scope value from your Brightspace App.
- State can be any value (this value is a security feature meant to protect against Cross Site request forgery. For testing purposes this value isn’t very important, but for Production apps please make sure that you use a cryptographically secure value.).
- Client Authorization set to “Send as Basic Auth header”.
Click “Request Token”
You will be prompted with a login window for your instance of Brightspace. Enter the Username and Password of the user you wish to perform API requests as and click Login
If successful, you should see a consent prompt to confirm the application use. Accept this prompt (note that this prompt only occurs for a user the first time they access the app).
The window should close and you will see an Access Token value entered into the collection. Scroll to the bottom of the window and click “Use Token”.
- Finally, click Create to create your Collection.
You now have a Postman Collection, connected to Brightspace using OAuth 2.0. The next step is to add an API Request to your Collection.
Adding Brightspace Requests to your Postman Collection
One of the powerful aspects of Postman is that you can add one or many API Requests to a Collection. Follow these steps to add a Request to your Collection:
Click the top left New button
Select a Request and start by giving it any Request name and Request Description
- Ensure your Collection is “Selected” as the save location. Click Save To {your Collection}.
At this point you will be brought back to the main Postman screen, but now you have the option of adding a specific API request. At this stage you could supply Postman the details of any Brightspace API route you want to test. For this article we are going to add a Request to GET a list of all quizzes that exist in a specific course:
For the first field specify GET as the HTTP method
- In the Request URL we need to build the full API endpoint, which will include your instance URL:
- Start with your instance URL (e.g. https://devcop.brightspace.com)
- Enter the URI of the API you want to call (e.g. /d2l/api/le/(version)/(orgUnitId)/quizzes/ )
Substitute the (version) value for your current API version
- Substitute your orgUnitId for the course to target
- The final value should look something like this: https://devcop.brightspace.com/d2l/api/le/1.28/8631/quizzes/
Click on the Authorization tab and ensure for Type that “Inherit auth from parent” is set
With the request details entered and the authorization specific click Send to test the new request
- In our example you should now receive back a 200 response with a series of quizzes currently available for your user to see in the specific orgUnit.
If no quizzes exist, you can expect a 404 for “no quizzes found”
- If your user doesn’t have permissions to see quizzes, you will receive a 403 “not authorized”
Advanced Uses of Postman
Postman contains additional features which both save time as well as increase understanding of an API route. Postman allows for Collection and/or Environment variables. These enable you to substitute values into your requests for quickly adding new endpoints or even testing in different instances. Here are some ideas to help you get started:
Create an environment variable that defines the URL of your Brightspace instance
- Create a version variable to store the value supplied in your API URIs
Another great feature is scripts. Postman contains a runtime environment (based on Node.js) which allows you to add dynamic code to your requests either pre-request or right after a call is made. Users can add pre-request and post-request scripts to collections folders or specific requests. We think scripts would be great for situations like:
Polling for an instance’s API version and supplying the value into a variable for a subsequent request
Saving the value of an OrgUnitId and passing it for a lookup in a following request
- Perform a calculation function before submitting the data in a POST API
Issues with Postman and Brightspace
Our evaluation of Postman was promising and positive. However, we did experience a couple of issues that you should be aware of.
Clearing Cookies – at the time of publishing this article we have noticed that there are no issues the first time OAuth tokens are generated. However, subsequent attempts have issues. To resolve this issue, we recommend to “Clear Cookies” within Postman. Doing so resolves the problem.
- No Login Redirection – When generating an OAuth token, the user is sent from Postman to the login page of the Brightspace instance they are developing against. Within Postman’s built-in browser there are no options for redirecting to a different Brightspace login page. This is only an issue if the user account you are developing with is not registered with the Identity Provider of your main login page.
We are evaluating both above issues. However, we believe they are both issues within Postman. We would be open to suggestions on how to better bypass these issues, and we will provide any updates we receive in this article.
Conclusion
Please let us know about your experience using Postman. Feel free to share with us any Postman Collections you develop. If there is another API testing client that you prefer over Postman, we would like to know so we can test it out too.
