This tutorial is intended to help you understand how to write a Tool Provider that works with a Tool Consumer like Canvas. We have created a basic Ruby on Rails application that implements a basic calculator. By following the steps below, you can take the code for the stand-alone calculator, or your own Rails application, and make it available to run from within an LTI-compliant LMS like Canvas.
This tutorial assumes that you have read through the basic steps for creating an LTI-compliant application, and that you have at least a little familiarity with Ruby on Rails.
Add this Ruby
Gem to the Gemfile of your Rails
This helps in performing most LTI tasks
such as validating and authenticating LTI requests.
gem 'ims-lti', '~> 1.1.8'
Step 2: Before tool consumers can send a request to your tool, they will have to add your app. To do so, they need a key and a secret. Create a new config file config/lti_settings.yml, and add a key and a secret to that file. The lti_settings.yml file should contain the following:
production: calculatorkey: 'FirstSecret' development: calculatorkey: 'FirstSecret'
config.lti_settings = Rails.application.config_for(:lti_settings)This variable will load the key and secret from your settings file.
Step 3: Along with a key and a secret, the tool consumer will also need a url where it can send a request. For that purpose, create a controller named lti with a launch endpoint (so the url can say '..../lti/launch' for readability). This launch endpoint will receive the post request from the tool consumer and we will validate and authenticate the LTI requests within this endpoint.
Step 4: When your app is launched from a Tool Consumer (such as Canvas), it will send a post request to your launch endpoint with a bunch of parameters. One of the received parameters in the request will be oauth_consumer_key. This key should be exactly the same as the one we defined in the settings.yml file. The first step in a request validation is to check whether this received key is present in your system. If the key is not present, then throw an error. Add the following code inside the launch endpoint for key validation:
if not Rails.configuration.lti_settings[params[:oauth_consumer_key]] render :launch_error, status: 401 return end
If the key is present, then we move to the second step of
validation, which is to (1) check whether the request is a valid LTI
request, and (2) verify the authenticity of the Tool Consumer.
require 'oauth/request_proxy/action_controller_request' @provider = IMS::LTI::ToolProvider.new( params[:oauth_consumer_key], Rails.configuration.lti_settings[params[:oauth_consumer_key]], params ) if not @provider.valid_request?(request) # the request wasn't validated render :launch_error, status: 401 return end
Step 6: At this point, you have a valid and authentic LTI request. In our example, we store the user id and name in a session and redirect the user to use calculator application. To do so, add the following code below the code of Step 5.
session[:user_id] = params.require :user_id session[:lis_person_name_full] = params.require :lis_person_name_full @lis_person_name_full = session[:lis_person_name_full] redirect_to calculator_path
Step 7: Now, if you try to register your application in Canvas, you will need XML configuration for your app. Therefore, you should create a page which provides XML configuration of your app. Following is the XML configuration of this calculator app. In our XML, we tell Canvas under lticm:options tag that we need our Calculator application on Course Navigation.
Calculator Calculator LTI Application http://localhost:3000/lti/launch public http://localhost:3000/lti/launch Calculator public enabled true
Now, you have all the things required to register an application
on Canvas: key, secret and XML configuration.
After pasting your XML configuration along with key and a secret
in Canvas, you should see your application in course navigation.
If you launch your application now, you will receive the
skip_before_action :verify_authenticity_token, only: :launch
If you launch your application once again, you should see the
following warning if your application is not running on
Step 11: Now, delete your application from Canvas and update your config file with https launch URL and add your application again.
Step 12: Even now, if you launch your application from Course Navigation menu, you will not see anything and rather you will see the following error in your browser console:
Refused to display 'https://localhost:3000/calculator' in a frame because it set 'X-Frame-Options' to 'sameorigin'.
after_action :allow_iframe, only: [:calculator] def allow_iframe response.headers.except! 'X-Frame-Options' end
Step 13: The last step is to update routes and also to create a launch_error page, because this is where we are redirecting the user if the request is not validated or authenticated. Create views/lit/launch_error.html.erb and add the following code to it:
Make sure you have a correct key and a secret to access the calculator application.
after_action :allow_iframe, only: [:launch] def allow_iframe response.headers.except! 'X-Frame-Options' end
Rails.application.routes.draw do get 'lti/launch' post 'lti/launch' get 'calculator', to: 'calculator#calculator' root 'calculator#calculator' end
Once you are done with all these steps, and Canvas has a valid
key and a secret, then you should see your application working
Read our next tutorial to learn how to send scores back to a tool consumer.