sinatra-canvas_auth 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2de2f77ea5c253f39b90e8fa838a3da4fd332392
+  data.tar.gz: 404e2f5985d52d798ba61f4680205cf56ffbcd0e
+SHA512:
+  metadata.gz: 1241210da5cc56803b178946eb18f4dbfba09b2f93239e641a01d20c86ca24963b4203792c2eb34f9c43d7e114bacd3bef3fc0071304d84c2d8766d5f4298575
+  data.tar.gz: afe435e636bbf4bbae985de9029d622b1da6ed93073f2509ca65f930da81e0b37581fde9b6d46fa5c25af32b57c763382e692a871638c2c870db019100dadc46

data/README.md

@@ -0,0 +1,180 @@
+# Sinatra::CanvasAuth
+
+CanvasAuth is a Sinatra extension that implements the [OAuth2 flow](https://canvas.instructure.com/doc/api/file.oauth.html) used for authenticating a user via [Canvas LMS](https://github.com/instructure/canvas-lms).
+
+This gem handles redirection of unauthenticated/unauthorized users, as well as the routing & API calls necessary for logging in/obtaining an access token, logging out/deleting an access token.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sinatra-canvas_auth'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sinatra-canvas_auth
+
+
+## Usage
+If you are developing a ["classic-style"](http://www.sinatrarb.com/intro.html#Modular%20vs.%20Classic%20Style) Sinatra app, require the files at the top of your app, enable sessions, and set the required configuration options.
+
+``` ruby
+require sinatra
+require sinatra/canvas_auth
+
+# These settings are required
+configure do
+    enable :sessions
+    set :canvas_url, 'https://ucdenver.instructure.com'
+    set :client_id, 10230000000000045
+    set :client_secret, '659df93f24affc25948ee437f8ac825edfa903d95e3a5ace0bb5ac4fb61686c6'
+end
+
+get '/' do
+    'Hello World'
+end
+```
+
+For "modular-style" apps, you must also explicitly register the extension
+``` ruby
+require sinatra/base
+require sinatra/canvas_auth
+
+class App < Sinatra::Base
+
+    # These settings are required
+    configure do
+        enable :sessions
+        set :canvas_url, 'https://ucdenver.instructure.com'
+        set :client_id, 10230000000000045
+        set :client_secret, '659df93f24affc25948ee437f8ac825edfa903d95e3a5ace0bb5ac4fb61686c6'
+    end
+
+    register Sinatra::CanvasAuth
+
+    get '/' do
+       'Hello World'
+    end
+end
+```
+
+## Configuration
+CanvasAuth pulls settings from your Sinatra app's configuration, which can be set with [the built-in DSL](http://www.sinatrarb.com/configuration.html).
+
+For simplicity, examples in this documentation hard-code configuration within the application, though it is often wise to use alternate methods when configuring sensitive data (e.g. API keys), especially when working with open source. Here are just a few options that can help you with this:
+* [Sinatra::ConfigFile](http://www.sinatrarb.com/contrib/config_file.html)
+* [Dotenv](https://github.com/bkeepers/dotenv)
+* [Figaro](https://github.com/laserlemon/figaro)
+
+CanvasAuth requires a baseline configuration to function, as Canvas API settings will differ between instances. Below is a full list of the available configuraiton options.
+
+#### Required Settings
+
+* **canvas_url** (String)
+
+  The full URL of the Canvas instance used for authentication.
+  ```ruby
+  set :canvas_url, 'https://ucdenver.instructure.com'
+  ```
+
+* **client_id** (String)
+
+  The client id (AKA "ID") for the developer key associated with your app. Developer keys can be requested [here](http://goo.gl/yu4lT), or created directly by Canvas admins by clicking "Developer Keys" on the sidebar under your account's admin panel.
+  ```ruby
+  set :client_id, 10230000000000045
+  ```
+
+* **client_secret** (String)
+
+  The 64 character client secret (AKA "Key") for the developer key associated with your app.
+  ```ruby
+  set :client_secret, '659df93f24affc25948ee437f8ac825edfa903d95e3a5ace0bb5ac4fb61686c6'
+  ```
+&nbsp;
+
+
+#### Optional Settings
+
+* **auth_paths** (Array)  
+  Default: [/.*/]  
+  To only require authentication for certain routes, they may be explicitly specified here with either strings or regular expression. By default, all app routes will require authentication.
+  ```ruby
+  set :auth_paths, ['/admin', /^\/courses\/(\d)+$]
+  ```
+
+  Alternative syntax:
+  ```ruby
+  authenticate '/admin', /^\/courses\/(\d)+$
+  ```
+
+* **unauthorized_redirect** (String)  
+  Default: "/unauthorized"  
+  If the above "authorized" setting is provided and returns falsy when called, the user will be redirected to this path.
+  ```ruby
+  set :unauthorized_redirect, '/not_allowed'
+  ```
+
+* **logout_redirect** (String)  
+  Default: "/logged-out"  
+  After a user is logged out, they will be redirected to this path.
+  ```ruby
+  set :logout_redirect, '/goodbye'
+  ```
+&nbsp;
+
+#### Callbacks
+
+The following are optional hooks called by CanvasAuth which allow you to customize certain behavior. They should be defined as [helper methods](http://www.sinatrarb.com/intro.html#Helpers) within your application.
+
+* **oauth_callback(oauth_response)**
+
+  Once the OAuth authentication request has been made, this method is called with the API response from Canvas as an argument. This may be used to define a custom response handling action, such as saving the user's token in a database.
+  ```ruby
+  helpers do
+    def oauth_callback(oauth_response)
+      uid = oauth_response['user']['id']
+      token = oauth_response['access_token']
+      db_connection.execute("UPDATE users SET access_token = ? where uid = ?", token, uid)
+    end
+  end
+  ```
+
+* **authorized()**
+
+  This method may be defined to check the authorization priveleges of a user once they have logged in. It should return truthy for authorized users, falsy otherwise. Since this is called without parameters, it generally makes use of session variables and/or settings which were set during the oauth_callback method or elsewhere in the app.
+  ```ruby
+  helpers do
+    def authorized
+      session[:allowed_roles].includes?(session[:user_roles])
+    end
+  end
+  ```
+
+## Miscellaneous Notes
+* CanvasAuth automatically assigns `session['user_id']` and `session['access_token']` to the values returned by the OAuth response, so there is no need to do this manually in your oauth_callback proc.
+
+* The following routes are defined by CanvasAuth for use in the OAuth flow and should not be overridden by your application:
+  * GET  /canvas-auth-login
+  * GET  /canvas-auth-logout
+  * POST /canvas-auth-token
+
+* The following routes are also defined by CanvasAuth, but only as placeholders that may (and should) be overridden by your application. They do not include any functionality and serve only as landing pages to prevent 404ing on the default redirects.
+  * GET /unauthorized
+  * GET /logged-out
+
+* All routes defined by CanvasAuth are permanently exempt from the requiring authentication, to avoid redirect loops.
+## Contributing
+
+Feeback, bug reports, and pull requests are welcome and appreciated.
+
+1. Fork it ( https://github.com/CUOnline/sinatra-canvas_auth/fork )
+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 a new Pull Request

data/lib/sinatra/canvas_auth/version.rb

@@ -0,0 +1,5 @@
+module Sinatra
+  module CanvasAuth
+    VERSION = "0.0.1"
+  end
+end

data/lib/sinatra/canvas_auth.rb

@@ -0,0 +1,123 @@
+require 'sinatra'
+require 'rest-client'
+
+module Sinatra
+  module CanvasAuth
+
+    DEFAULT_SETTINGS = {
+      :auth_paths            => [/.*/],
+      :canvas_url            => nil,
+      :client_id             => nil,
+      :client_secret         => nil,
+      :login_path            => '/canvas-auth-login',
+      :token_path            => '/canvas-auth-token',
+      :logout_path           => '/canvas-auth-logout',
+      :logout_redirect       => '/logged-out',
+      :unauthorized_redirect => '/unauthorized'
+    }.freeze
+
+    # Just a prettier syntax for setting auth_paths
+    def authenticate(*paths)
+      set :auth_paths, paths
+    end
+
+    def self.registered(app)
+      self.merge_defaults(app)
+
+      app.get app.login_path do
+        redirect_uri = "#{request.scheme}://#{request.host_with_port}" \
+                       "#{request.env['SCRIPT_NAME']}#{app.token_path}"
+
+        redirect_params = "client_id=#{app.client_id}&" \
+                          "response_type=code&" \
+                          "state=#{CGI.escape(params['state'])}&" \
+                          "redirect_uri=#{CGI.escape(redirect_uri)}"
+
+        ['scope', 'purpose', 'force_login', 'unique_id'].each do |optional_param|
+          if params[optional_param]
+            redirect_params += "&#{optional_param}=#{CGI.escape(params[optional_param])}"
+          end
+        end
+
+        redirect "#{app.canvas_url}/login/oauth2/auth?#{redirect_params}"
+      end
+
+      app.get app.token_path do
+        payload = {
+          :code          => params['code'],
+          :client_id     => settings.client_id,
+          :client_secret => settings.client_secret
+        }
+
+        response = RestClient.post("#{settings.canvas_url}/login/oauth2/token", payload)
+        response = JSON.parse(response)
+        session['user_id'] = response['user']['id']
+        session['access_token'] = response['access_token']
+
+        oauth_callback(response) if self.respond_to?(:oauth_callback)
+
+        redirect params['state']
+      end
+
+      app.get app.logout_path do
+        if session['access_token']
+          delete_url = "#{settings.canvas_url}/login/oauth2/token"
+          delete_url += "&expire_sessions=1" if params['expire_sessions']
+
+          RestClient::Request.execute({
+            :method  => :delete,
+            :url     => delete_url,
+            :headers => {
+              :authorization => "Bearer #{session['access_token']}"
+            }
+          })
+        end
+        session.clear
+        redirect to(settings.logout_redirect)
+      end
+
+      # These two routes exist to prevent 404'ing with default options, but
+      # ideally they should be overridden by the app, or alternate paths given
+      app.get '/unauthorized' do
+        'Your canvas account unauthorized to view this resource'
+      end
+
+      app.get '/logged-out' do
+        "You have been logged out <a href='canvas-auth-login'>" \
+        "Click here</a> to log in again."
+      end
+
+
+      # Redirect unauthenticated/unauthorized users before hitting app routes
+      app.before do
+        current_path = "#{request.env['SCRIPT_NAME']}#{request.env['PATH_INFO']}"
+        if CanvasAuth.auth_path?(self.settings, current_path)
+          if session['user_id'].nil?
+            redirect "#{request.env['SCRIPT_NAME']}#{settings.login_path}?state=#{current_path}"
+          elsif self.respond_to?(:authorized) && !authorized
+            redirect "#{request.env['SCRIPT_NAME']}#{settings.unauthorized_redirect}"
+          end
+        end
+      end
+    end
+
+    # Should the current path ask for authentication or is it public?
+    def self.auth_path?(app, current_path)
+      exempt_paths = [ app.login_path, app.token_path, app.logout_path,
+                       app.logout_redirect, app.unauthorized_redirect ]
+
+      app.auth_paths.select{ |p| current_path.match(p) }.any? &&
+      !exempt_paths.include?(current_path)
+    end
+
+    def self.merge_defaults(app)
+      DEFAULT_SETTINGS.each do |key, value|
+        if !app.respond_to?(key)
+          app.set key, value
+        end
+      end
+    end
+  end
+
+  register CanvasAuth
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-canvas_auth
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Connor Ford
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: 
+email: connor.ford@ucdenver.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sinatra/canvas_auth.rb
+- lib/sinatra/canvas_auth/version.rb
+homepage: https://github.com/cuonline
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Canvas LMS OAuth flow for Sinatra
+test_files: []