omniauth-blackboard 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dcc94b1ad3db925e8d0c5f4bcc0290eb5bca2445
+  data.tar.gz: ef7b91ddb5cb2837dd4d3677d20f8dcb41d35797
+SHA512:
+  metadata.gz: 0a2b71fd617d8b8a72d47b0f8c8596f636fcee9e46d04eb11e30d97e94697c691569ac12e1f3cf8d1f8678d94f127888799b376ac6dbaa01200b25ef86bcd2e5
+  data.tar.gz: b3e5a98587eac349437880ed1294b580aa5ab05f57f30e8c3e54a7b0c3eee1ad62b7882a33c477d3a2c5b6e318af5bb1999f8e25d3c593e2afe90ccc7da7f59d

data/README.md

@@ -0,0 +1,184 @@
+# OmniAuth Blackboard [![Build Status](https://travis-ci.org/atomicjolt/omniauth-blackboard.svg?branch=master)](https://travis-ci.org/atomicjolt/omniauth-blackboard)
+Gem to authenticate with Blackboard via OAuth2
+
+# Background
+OmniAuth Blackboard grew out of the need to simplify the process of setting up LTI
+and connecting a user account on to Blackboard on various projects built by
+[Atomic Jolt](http://www.atomicjolt.com).
+
+# Example
+[Atomic Jolt](http://www.atomicjolt.com) has created an LTI started application that demonstrates
+how to use the OAuth gem:
+[LTI Starter App](https://github.com/atomicjolt/lti_starter_app)
+
+# Setup
+By default omniauth-blackboard will attempt to authenticate with https://bd-partner-a-original.blackboard.com.
+
+**NOTE**: you will need to set `env['rack.session']['oauth_site']` to the current
+Blackboard instance that you wish to OAuth with. By default this is https://bd-partner-a-original.blackboard.com
+
+-- OR --
+
+to dynamically set the blackboard site url do one of the following.
+
+## Standard setup
+
+```ruby
+use OmniAuth::Builder do
+  provider :blackboard, 'blackboard_key', 'blackboard_secret', :setup => lambda{|env|
+    request = Rack::Request.new(env)
+    env['omniauth.strategy'].options[:client_options].site = env['rack.session']['oauth_site']
+  }
+end
+```
+
+## Setup with Devise
+
+```ruby
+config.omniauth :blackboard, 'blackboard_key', 'blackboard_secret', :setup => lambda{|env|
+  request = Rack::Request.new(env)
+  env['omniauth.strategy'].options[:client_options].site = env['rack.session']['oauth_site']
+}
+```
+
+## Alternative Setup
+
+In this setup, you do not have to set `env['rack.session']['oauth_site']`
+
+```ruby
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :blackboard, APP_CONFIG['blackboard_client_id'], APP_CONFIG['blackboard_client_secret'],
+  {
+    :client_options => {
+      :site => APP_CONFIG['blackboard_host']
+    }
+  }
+end
+```
+
+
+# Blackboard Configuration
+
+If you are running your own installation of blackboard, you can generate a client ID
+and secret in the Site Admin account of your Blackboard install. There will be a
+"Developer Keys" tab on the left navigation sidebar. For more information,
+consult the [Blackboard OAuth Documentation](https://bd-partner-a-original.blackboard.com/doc/api/file.oauth.html)
+
+
+# State
+
+In most cases your application will need to restore state after handling the OAuth process
+with Blackboard. Since many applications that integrate with Blackboard will be launched via the LTI
+protocol inside of an iframe sessions may not be available. To restore application state the
+omniauth-blackboard gem uses the "state" parameter provided by the LTI proctocol. You will need
+to add the following code to your application to take advantage of this functionality:
+
+
+Add the following initializer in `config/initializers/omniauth.rb`:
+
+```ruby
+OmniAuth.config.before_request_phase do |env|
+  request = Rack::Request.new(env)
+  state = "#{SecureRandom.hex(24)}#{DateTime.now.to_i}"
+  OauthState.create!(state: state, payload: request.params.to_json)
+  env["omniauth.strategy"].options[:authorize_params].state = state
+
+  # Bye default omniauth will store all params in the session. The code above
+  # stores the values in the database so we remove the values from the session
+  # since the amount of data in the original params object will overflow the
+  # allowed cookie size
+  env["rack.session"].delete("omniauth.params")
+end
+```
+
+Add the following middleware to `lib/middlware/oauth_state_middleware.rb`:
+
+```ruby
+class OauthStateMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+    if request.params["state"] && request.params["code"]
+      if oauth_state = OauthState.find_by(state: request.params["state"])
+        # Restore the param from before the OAuth dance
+        state_params = JSON.parse(oauth_state.payload) || {}
+        state_params.each do |key, value|
+          request.update_param(key, value)
+        end
+        application_instance = ApplicationInstance.find_by(lti_key: state_params["oauth_consumer_key"])
+        env["blackboard.url"] = application_instance.lti_consumer_uri
+        oauth_state.destroy
+      else
+        raise OauthStateMiddlewareException, "Invalid state in OAuth callback"
+      end
+    end
+    @app.call(env)
+  end
+end
+
+class OauthStateMiddlewareException < RuntimeError
+end
+```
+
+This middleware relies upon two models - OauthState and ApplicationInstance. OauthState is used to
+store relevant state before sending the user to Blackboard to finish the OAuth. ApplicationInstance is
+model used in Atomic Jolt projects that is used to store the Blackboard Url so that it can be reset in
+the environment. You don't need to implement the same model, but you will need to store the user's
+Blackboard URL somewhere before sending the user to OAuth with Blackboard. Change the following lines in the
+above code to recover the Blackboard URL from where ever it is stored:
+
+```
+application_instance = ApplicationInstance.find_by(lti_key: state_params["oauth_consumer_key"])
+env["blackboard.url"] = application_instance.lti_consumer_uri
+```
+
+The OauthState model looks like this:
+```
+class OauthState < ActiveRecord::Base
+  validates :state, presence: true, uniqueness: true
+end
+```
+
+With the following schema:
+```
+create_table "oauth_states", force: :cascade do |t|
+  t.string   "state"
+  t.text     "payload"
+  t.datetime "created_at", null: false
+  t.datetime "updated_at", null: false
+  t.index ["state"], name: "index_oauth_states_on_state", using: :btree
+end
+```
+
+Last, enable the middleware by adding the following to `config/application.rb`:
+
+```ruby
+# Middleware that can restore state after an OAuth request
+config.middleware.insert_before 0, "OauthStateMiddleware"
+```
+
+
+# License
+
+Copyright (C) 2012-2017 by Justin Ball and Atomic Jolt.
+
+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/Rakefile

@@ -0,0 +1,16 @@
+#!/usr/bin/env rake
+$: << File.dirname(__FILE__)
+
+require 'bundler'
+require 'rake'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+task :default => [:spec]
+task :test => [:spec]
+
+desc "run spec tests"
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end

data/lib/omniauth-blackboard.rb

@@ -0,0 +1,2 @@
+require "omniauth-blackboard/version"
+require "omniauth/strategies/blackboard"

data/lib/omniauth-blackboard/version.rb

@@ -0,0 +1,5 @@
+module OmniAuth
+  module Blackboard
+    VERSION = "1.0.0".freeze
+  end
+end

data/lib/omniauth/strategies/blackboard.rb

@@ -0,0 +1,70 @@
+require "omniauth-oauth2"
+
+module OmniAuth
+  module Strategies
+    class Blackboard < OmniAuth::Strategies::OAuth2
+
+      option :name, "blackboard"
+
+      option :client_options,
+             site:          "https://bd-partner-a-original.blackboard.com",
+             authorize_url: "/learn/api/public/v1/oauth2/authorizationcode",
+             token_url:     "/learn/api/public/v1/oauth2/token"
+
+      # Blackboard does use state but we want to control it rather than letting
+      # omniauth-oauth2 handle it.
+      option :provider_ignores_state, true
+
+      option :token_params,
+             parse: :json
+
+      uid do
+        access_token["user"]["id"]
+      end
+
+      info do
+        {
+          "name" => raw_info["name"],
+          "email" => raw_info["primary_email"],
+          "bio" => raw_info["bio"],
+          "title" => raw_info["title"],
+          "nickname" => raw_info["login_id"],
+          "active_avatar" => raw_info["avatar_url"],
+          "url" => access_token.client.site
+        }
+      end
+
+      extra do
+        { raw_info: raw_info }
+      end
+
+      def raw_info
+        @raw_info ||= access_token.get("/learn/api/public/v1/users/#{access_token['user']['id']}").parsed
+      end
+
+      # Passing any query string value to Blackboard will result in:
+      # redirect_uri does not match client settings
+      # so we set the value to empty string
+      def query_string
+        ""
+      end
+
+      # Override authorize_params so that we can be deliberate about the value for state
+      # and not use the session which is unavailable inside of an iframe for some
+      # browsers (ie Safari)
+      def authorize_params
+        # Only set state if it hasn't already been set
+        options.authorize_params[:state] ||= SecureRandom.hex(24)
+        params = options.authorize_params.merge(options_for("authorize"))
+        if OmniAuth.config.test_mode
+          @env ||= {}
+          @env["rack.session"] ||= {}
+        end
+        params
+      end
+
+    end
+  end
+end
+
+OmniAuth.config.add_camelization "blackboard", "Blackboard"

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: omniauth-blackboard
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Justin Ball
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-11-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: omniauth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.3.1
+- !ruby/object:Gem::Dependency
+  name: omniauth-oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: OmniAuth Oauth2 strategy for Blackboard.
+email: justin@atomicjolt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/omniauth-blackboard.rb
+- lib/omniauth-blackboard/version.rb
+- lib/omniauth/strategies/blackboard.rb
+homepage: https://github.com/atomicjolt/omniauth-blackboard
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.13
+signing_key: 
+specification_version: 4
+summary: OmniAuth Oauth2 strategy for Blackboard.
+test_files: []