canvas_oauth_engine 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 - 2015 Instructure, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,102 @@
+# 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.
+
+## 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 exec 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

data/Rakefile

@@ -0,0 +1,28 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'CanvasOauth'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+task :default => :spec

data/app/controllers/canvas_oauth/application_controller.rb

@@ -0,0 +1,5 @@
+module CanvasOauth
+  class ApplicationController < ActionController::Base
+    include CanvasOauth::CanvasApplication
+  end
+end

data/app/controllers/canvas_oauth/canvas_controller.rb

@@ -0,0 +1,25 @@
+module CanvasOauth
+  class CanvasController < CanvasOauth::ApplicationController
+    skip_before_filter :request_canvas_authentication
+
+    def oauth
+      if verify_oauth2_state(params[:state]) && params[:code]
+        if token = canvas.get_access_token(params[:code])
+          if CanvasOauth::Authorization.cache_token(token, user_id, tool_consumer_instance_guid)
+            redirect_to main_app.root_path
+          else
+            render text: "Error: unable to save token"
+          end
+        else
+          render text: "Error: invalid code - #{params[:code]}"
+        end
+      else
+        render text: "#{CanvasOauth::Config.tool_name} needs access to your account in order to function properly. Please try again and click log in to approve the integration."
+      end
+    end
+
+    def verify_oauth2_state(callback_state)
+      callback_state.present? && callback_state == session.delete(:oauth2_state)
+    end
+  end
+end

data/app/models/canvas_oauth/authorization.rb

@@ -0,0 +1,26 @@
+module CanvasOauth
+  class Authorization < ActiveRecord::Base
+    validates :canvas_user_id, :token, :last_used_at, presence: true
+
+    def self.cache_token(token, user_id, tool_consumer_instance_guid)
+      create(
+        token: token,
+        canvas_user_id: user_id,
+        last_used_at: Time.now,
+        tool_consumer_instance_guid: tool_consumer_instance_guid
+      )
+    end
+
+    def self.fetch_token(user_id, tool_consumer_instance_guid)
+      user_tokens = where(canvas_user_id: user_id, tool_consumer_instance_guid: tool_consumer_instance_guid).order("created_at DESC")
+      if canvas_auth = user_tokens.first
+        canvas_auth.update_attribute(:last_used_at, Time.now)
+        return canvas_auth.token
+      end
+    end
+
+    def self.clear_tokens(user_id, tool_consumer_instance_guid)
+      where(canvas_user_id: user_id, tool_consumer_instance_guid: tool_consumer_instance_guid).destroy_all
+    end
+  end
+end

data/config/canvas.yml.example

@@ -0,0 +1,12 @@
+default: &default
+  key: your_key
+  secret: your_secret
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+cucumber:
+  <<: *default

data/config/routes.rb

@@ -0,0 +1,3 @@
+CanvasOauth::Engine.routes.draw do
+  match "/", to: "canvas#oauth", via: :get, as: :canvas_oauth
+end

data/db/migrate/20121121005358_create_canvas_oauth_authorizations.rb

@@ -0,0 +1,15 @@
+class CreateCanvasOauthAuthorizations < ActiveRecord::Migration
+  def change
+    create_table "canvas_oauth_authorizations", :force => true do |t|
+      t.integer  "canvas_user_id", :limit => 8
+      t.string   "tool_consumer_instance_guid", :null => false
+      t.string   "token"
+      t.datetime "last_used_at"
+      t.datetime "created_at",                  :null => false
+      t.datetime "updated_at",                  :null => false
+    end
+
+    add_index :canvas_oauth_authorizations, [:canvas_user_id, :tool_consumer_instance_guid],
+      name: 'index_canvas_oauth_auths_on_user_id_and_tciguid'
+  end
+end

data/lib/canvas_oauth.rb

@@ -0,0 +1,25 @@
+require 'ostruct'
+
+require 'httparty'
+require 'link_header'
+
+require "canvas_oauth/config"
+require "canvas_oauth/canvas_application"
+require 'canvas_oauth/canvas_api'
+require 'canvas_oauth/canvas_api_extensions'
+require 'canvas_oauth/canvas_config'
+
+module CanvasOauth
+  mattr_accessor :app_root
+
+  def self.setup
+    yield self
+  end
+
+  def self.config
+    yield(CanvasOauth::Config)
+  end
+end
+
+require "canvas_oauth/engine"
+

data/lib/canvas_oauth/canvas_api.rb

@@ -0,0 +1,249 @@
+module CanvasOauth
+  class CanvasApi
+    include HTTParty
+    PER_PAGE = 50
+
+    attr_accessor :token, :key, :secret
+    attr_reader :canvas_url
+
+    def initialize(canvas_url, token, key, secret)
+      self.canvas_url = canvas_url
+      self.token = token
+      self.key = key
+      self.secret = secret
+    end
+
+    def authenticated_request(method, *params)
+      params << {} if params.size == 1
+
+      params.last[:headers] ||= {}
+      params.last[:headers]['Authorization'] = "Bearer #{token}"
+
+      start = Time.now
+
+      response = self.class.send(method, *params)
+
+      Rails.logger.info {
+        stop = Time.now
+        elapsed = ((stop - start) * 1000).round(2)
+
+        params.last[:headers].reject! { |k| k == 'Authorization' }
+        "API call (#{elapsed}ms): #{method} #{params.inspect}"
+      }
+
+      if response && response.unauthorized?
+        if response.headers['WWW-Authenticate'].present?
+          raise CanvasApi::Authenticate
+        else
+          raise CanvasApi::Unauthorized
+        end
+      else
+        return response
+      end
+    end
+
+    def paginated_get(*params)
+      params[1] ||= {}
+      params[1][:query] ||= {}
+      params[1][:query][:per_page] = PER_PAGE
+
+      all_pages = []
+
+      while params[0] do
+        if current_page = authenticated_get(*params)
+          all_pages += current_page if valid_page?(current_page)
+
+          links = LinkHeader.parse(current_page.headers['link'])
+          params[0] = links.find_link(["rel", "next"]).try(:href)
+        else
+          params[0] = nil
+        end
+      end
+
+      all_pages
+    end
+
+    def get_report(account_id, report_type, params)
+      report = authenticated_post("/api/v1/accounts/#{account_id}/reports/#{report_type}", { body: params })
+      report = authenticated_get "/api/v1/accounts/#{account_id}/reports/#{report_type}/#{report['id']}"
+      while report['status'] == 'running'
+        sleep(4)
+        report = authenticated_get "/api/v1/accounts/#{account_id}/reports/#{report_type}/#{report['id']}"
+      end
+
+      if report['status'] == 'complete'
+        file_id = report['file_url'].match(/files\/([0-9]+)\/download/)[1]
+        file = get_file(file_id)
+        return hash_csv(self.class.get(file['url'], limit: 15).parsed_response)
+      else
+        return report
+      end
+    end
+
+    def valid_page?(page)
+      page && page.size > 0
+    end
+
+    def get_file(file_id)
+      authenticated_get "/api/v1/files/#{file_id}"
+    end
+
+    def get_accounts_provisioning_report(account_id)
+      get_report(account_id, :provisioning_csv, 'parameters[accounts]' => true)
+    end
+
+    #Needs to be refactored to somewhere more generic
+    def hash_csv(csv_string)
+      require 'csv'
+
+      csv = CSV.parse(csv_string)
+      headers = csv.shift
+      output = []
+
+      csv.each do |row|
+        hash = {}
+        headers.each do |header|
+          hash[header] = row.shift.to_s
+        end
+        output << hash
+      end
+
+      return output
+    end
+
+    def authenticated_get(*params)
+      authenticated_request(:get, *params)
+    end
+
+    def authenticated_post(*params)
+      authenticated_request(:post, *params)
+    end
+
+    def authenticated_put(*params)
+      authenticated_request(:put, *params)
+    end
+
+    def get_courses
+      paginated_get "/api/v1/courses"
+    end
+
+    def get_account(account_id)
+      authenticated_get "/api/v1/accounts/#{account_id}"
+    end
+
+    def get_account_sub_accounts(account_id)
+      paginated_get "/api/v1/accounts/#{account_id}/sub_accounts", { query: { :recursive => true } }
+    end
+
+    def get_account_courses(account_id)
+      paginated_get "/api/v1/accounts/#{account_id}/courses"
+    end
+
+    def get_account_users(account_id)
+      paginated_get "/api/v1/accounts/#{account_id}/users"
+    end
+
+    def get_course(course_id)
+      authenticated_get "/api/v1/courses/#{course_id}"
+    end
+
+    def get_section_enrollments(section_id)
+      paginated_get "/api/v1/sections/#{section_id}/enrollments"
+    end
+
+    def get_user_enrollments(user_id)
+      paginated_get "/api/v1/users/#{user_id}/enrollments"
+    end
+
+    def get_course_users(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/users"
+    end
+
+    def get_all_course_users(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/users", { query: {enrollment_state: ["active","invited","rejected","completed","inactive"] } }
+    end
+
+    def get_course_teachers_and_tas(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/users", { query: { enrollment_type: ['teacher', 'ta'] } }
+    end
+
+    def get_course_students(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/students"
+    end
+
+    def get_section(section_id)
+      authenticated_get "/api/v1/sections/#{section_id}"
+    end
+
+    def get_sections(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/sections", { query: { :include => ['students', 'avatar_url', 'enrollments'] } }
+    end
+
+    def get_assignments(course_id)
+      paginated_get "/api/v1/courses/#{course_id}/assignments"
+    end
+
+    def get_assignment(course_id, assignment_id)
+      authenticated_get "/api/v1/courses/#{course_id}/assignments/#{assignment_id}"
+    end
+
+    def get_user_profile(user_id)
+      authenticated_get "/api/v1/users/#{user_id}/profile"
+    end
+
+    def create_assignment(course_id, params)
+      authenticated_post "/api/v1/courses/#{course_id}/assignments", { body: { assignment: params } }
+    end
+
+    def grade_assignment(course_id, assignment_id, user_id, params)
+      authenticated_put "/api/v1/courses/#{course_id}/assignments/#{assignment_id}/submissions/#{user_id}", { body: params }
+    end
+
+    def course_account_id(course_id)
+      course = get_course(course_id)
+      course['account_id'] if course
+    end
+
+    def root_account_id(account_id)
+      if account_id && account = get_account(account_id)
+        root_id = account['root_account_id']
+      end
+
+      root_id || account_id
+    end
+
+    def course_root_account_id(course_id)
+      root_account_id(course_account_id(course_id))
+    end
+
+    def auth_url(redirect_uri, oauth2_state)
+      "#{canvas_url}/login/oauth2/auth?client_id=#{key}&response_type=code&state=#{oauth2_state}&redirect_uri=#{redirect_uri}"
+    end
+
+    def get_access_token(code)
+      params = {
+        body: {
+          client_id: key,
+          client_secret: secret,
+          code: code
+        }
+      }
+
+      response = self.class.post '/login/oauth2/token', params
+      self.token = response['access_token']
+    end
+
+    def hex_sis_id(name, value)
+      hex = value.unpack("H*")[0]
+      return "hex:#{name}:#{hex}"
+    end
+
+    def canvas_url=(value)
+      @canvas_url = value
+      self.class.base_uri(value)
+    end
+  end
+
+  class CanvasApi::Unauthorized < StandardError ; end
+  class CanvasApi::Authenticate < StandardError ; end
+end