canvas_oauth_engine

CanvasOauth

CanvasOauth is a mountable engine for handling the oauth workflow with canvas and making api calls from your rails app. This is tested with Rails 3.2, we'll be looking at verifying with Rails 4 soon.

Warning

The current version of this gem relies heavily on being able to access the user session. Since LTI apps generally run in an iframe inside the LMS, this means that tools using this engine MUST run on the same root domain as the LMS they are plugging into. This is obviously not ideal, and we will be working to remove this limitation in the future.

Installation

Add the gem to your Gemfile with the following line, and then bundle install

gem 'canvas_oauth_engine', :require => 'canvas_oauth'

Then, mount the engine to your app by adding this line to your routes.rb file

mount CanvasOauth::Engine => "/canvas_oauth"

Next, include the engine in your ApplicationController

class ApplicationController < ActionController::Base
  include CanvasOauth::CanvasApplication

  ...
end

After that, create an canvas.yml file in your config/ folder that looks something like this (or see config/canvas.yml.example for a template):

default: &default
  key: your_key
  secret: your_secret

development:
  <<: *default

test:
  <<: *default

production:
  <<: *default

The values of key and secret should be set from the developer key that you generate in the canvas application.

Finally, run migrations:

bundle install
bundle exec rake railties:install:migrations
bundle exec rake db:migrate

This will create the canvas_oauth_authorizations table which stores successful oauth tokens for later use, so the user does not have to accept the oauth login each time they use the app.

Usage

The engine only uses one url, whatever it is mounted to, to serve as the redirect_url in the oauth workflow.

The engine sets up a global before_filter, which checks for a valid oauth token, and if one does not exist, starts the oauth login flow. It handles posting the oauth request, verifying the result and redirecting to the application root. It exposes the following methods to your controllers:

• canvas
• canvas_token

The first is an instance of HTTParty ready to make api requests to your canvas application. The second is if you need access to the oauth token directly.

Configuring the Tool Consumer

You will a developer key and secret from canvas, which should be entered into you canvas.yml file.

Example

You can see and interact with an example of an app using this engine by looking at spec/dummy. This is a full rails app which integrates the gem and has a simple index page that says 'Hello Oauth' if the app is launched and the oauth flow is successful.

About Oauth

TODO...

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request