Recently I was asked to create a custom grading tool based on rubrics, which requires modifying student grade data. I had created a LTI toolkit to run some reports and automate SIS integration workflows, in that scenario I was using a token generated in a service account. But using a service account token to modify grades is not an accepted method. For grading we want to be able to verify a few important details and take advantage of existing functionality within Canvas:
The user has access to the course (masquerading is technically possible, but prone to errors)
The example used for this post assumes the application will be launched from within Canvas using LTI integration. If you have not yet worked through OAuth and LTI, these articles can provide an overview of how to get started before you dive into OAuth2:
The first step towards OAuth2 is completing the LTI install of your application within your Canvas instance. If you have not created an LTI application yet, I suggest completing the three LTI posts mentioned above, I will not cover those steps again here. .NET LTI Project - Part 1 - Connect to Canvas covers steps for registering your application in Canvas.
For the simple application associated with this example, I generated the LTI XML using the tool found here:
This method call (/home/oauth2response) will line up with the source code associated with this example.
The result of creating the developer key will generate a unique ID for your redirect:
There are three <appSettings> variables that we will use for this first run at the OAuth2 workflow.
"oauth2ClientId" - this is the value created in the Developer Key (screen shot above)
"consumerKey" - this is the consuer key you assigned during the LTI install of your application
"consumerSecret" - this is the shared secret you assigned during the LTI install of your application
Store these three variables in the web.config, see the associated source code for a reference.
Using the sample project as an aide, I'll walk you through the first part of the OAuth2 workflow which is very straight forward. The sample project was created from the default ASP.NET MVC project template, and will use the default HomeController.
Note: The sample project was created with as few steps as possible, it is a simple MVC application with a single controller. This is not a recommended template for a production application, but only an attempt to provide a simple, clean easy to follow example. After following along with this example, I strongly recommend thinking through the steps, and building your own solution.
Using Visual Studio to view the source code you will find a single controller: HomeController.cs
If you browse to the default URL you will see the home page (https://your.domain.com) There is nothing fancy, basically the default home page that was generated by the MVC template with modified content and links. You can use this page to verify your web server is setup properly.
There are two additional methods associated with this example:
The OAauth2 Request Method: oauth2Request()
This is the method defined in the LTI XML above, the method that Canvas will use to execute the launch request. The LTI launch request must be a POST. If you would like to test this method you can use Postman to debug this method manually by making a POST calll to https://your.domain.com/home/oauth2Request
I have included helper classes that will handle LTI parameters received (oauthHelper.cs and ltiLaundhParams.cs), more importantly it will parse the LTI launch parameters and validate the OAuth signature. Step through the code if you would like to learn more about LTI launch parameters. A manual call from Postman will fail validation and return the result.cshtml view with an associated message.
With the debugger running, launch the app from Canvas and confirm that LTI validation is successful. Validation of the OAuth signature depends on the "consuerKey" and "consumerSecret" that you stored in the web.config. Looking at the constructor of oauthHelper.cs you will see where the "consuerSecret" is read from the config file and the OAuth signature is verified. Once the LTI parameters pass validation the response will be a redirect back to Canvas. In the browser you should see a prompt from Canvas asking the user to authorize access on behalf of the user.
By clicking "Authorize" you are prompting Canvas to redirect back to the application server, your web server, at the URL you defined when you created the Developer Key earlier: https://your.domain.com/home/oauth2Response
The OAuth2 Response Method: oauth2Response()
This is the method that Canvas will call if the user clicks the "Authorize" button, shown in the screen shot above. In the source code associated with this example, the web server will return a simple Success!! message to verify that the loop has been closed. Get this much of the application working and you have Step 1 working, and part of Step 2.
Create a Developer Key, pointing the redirect URL to your "oauth2Response" method
Install your application in Canvas, directing the LTI launch URL to the "oauth2Request" method.
Make sure your web.config has the three required parameters:
Launch the app from Canvas, confirm that the OAuth signature passes validation and you receive the "Authorize" option in the browser
Click "Authorize" and confirm you receive the "Sucess!!" response in the browser
I felt this was a good place to start, enough to get things working without being too overwhelming. Getting this far you have verified that your dev environment is working properly, and that Canvas is properly configured. Next steps include requesting a user token and caching some values for reuse. If you don't have a database available there are many options: