A Beginners guide to OAuth2 authentication with Canvas and Postman

Ilias el Matani

Introduction

In this blog post, we’ll delve into the world of OAuth2 authentication, exploring how to securely communicate with the Canvas Learning Management System (LMS) API using Postman. From setting up OAuth2 flows to making your first API calls, this blog will equip you with the knowledge and practical skills needed to integrate your applications with Canvas seamlessly. Whether you’re a developer, educator, or Canvas administrator, this guide will simplify the complexities of API communication within the Canvas environment.

What is OAuth2?

OAuth2 is an industry-standard protocol that enables users to grant third-party applications limited access to their resources without revealing their passwords. In this section, we’ll explore the OAuth2 framework, essential concepts, and the OAuth2 flow specific to Canvas. Understanding these fundamentals is crucial for ensuring secure and efficient API communication.

Understanding OAuth2 authorization flow

OAuth2 is an industry-standard protocol that defines the authorization flow between a user, a client application, and the authorization server. In the context of Canvas, this flow follows the Authorization Code Grant type. Let’s break down the OAuth2 flow specific to Canvas: OAuth2 flow specific to Canvas

Practical Application in Postman

Transitioning from theory to practice, let's dive into setting up OAuth2 authorization in Postman for the Canvas API. We'll configure Postman with the necessary details obtained from the Canvas instance and execute requests to understand the authentication flow. This hands-on approach will bridge the gap between theoretical knowledge and practical implementation.

Create a Developer Key in Canvas

First, we will create a developer key in Canvas. This key serves as the foundation for secure authentication and authorization within the OAuth2 flow. It provides the necessary credentials, including a Client ID and Client Secret, that client applications use to authenticate themselves and request access to Canvas resources. Without this key, the OAuth2 flow cannot proceed, making it the crucial first step in the integration process. Let’s dive in and create our Developer Key:

  1. Log in to your Canvas instance as an administrator.
  2. Navigate to the Admin settings.
  3. Click on Developer Keys.
  4. Click on the Add Developer Key button.
  5. Provide a name for your developer key and specify the redirect URI. This should match the callback URL you'll use in Postman.
  6. Click Save and note down the Client ID and Client Secret.

Set Up OAuth2 Authorization in Postman

  1. Open Postman and create a new request collection for your Canvas API requests.

  2. Create a new request within the collection for OAuth2 authorization. In the request configuration, set the following details:

    • Request URL: http://<canvas-instance-url>/login/oauth2/auth
    • HTTP Method: GET
    • Parameters:
      • client_id: The Client ID obtained from your Canvas developer key.
      • response_type: Set this to code.
      • state: A random string to maintain state.
      • redirect_uri: The callback URL you specified earlier.
      • scope: The scope of access required. For example, url:GET|/api/v1/accounts.

  3. Send the request to initiate the OAuth2 authorization flow.

Authorize Access

After sending the request, you'll be redirected to the Canvas login page. Log in with your Canvas credentials and grant authorization for the Postman application to access your Canvas resources.

Retrieve Authorization Code

Once authorization is granted, Canvas will redirect you back to the callback URL specified in Postman. Note the authorization code appended to the callback URL.

Exchange Authorization Code for Access Token

Create a new request within your Postman collection to exchange the authorization code for an access token. Configure the request with the following details:

  • Request URL: http://<canvas-instance-url>/login/oauth2/token
  • HTTP Method: POST
  • Headers:
    • Content-Type: application/x-www-form-urlencoded
  • Body:
    • grant_type: authorization_code
    • client_id: The Client ID obtained from your Canvas developer key.
    • client_secret: The Client Secret obtained from your Canvas developer key.
    • redirect_uri: The same redirect URI used in the authorization request.
    • code: The authorization code obtained from the callback URL.

Send the request to exchange the authorization code for an access token.

Retrieve User Information with Access Token

Create another request within your Postman collection to retrieve information about the authenticated user. Configure the request with the following details:

  • Request URL: http://<canvas-instance-url>/api/v1/users/self
  • HTTP Method: GET
  • Headers:
    • Authorization: Bearer <access token>

Replace <access token> with the access token obtained in the previous step. Send the request to retrieve information about the authenticated user.

By following these steps, you’ll successfully set up OAuth2 authorization in Postman for the Canvas API, allowing you to make authenticated requests seamlessly. Happy integrating!