panda_pal 5.0.0 → 5.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b728d9c41289ccb3ddeba5c13245345750900733052dd26482f1f2efc2d048a8
-  data.tar.gz: e5418d426bbe784e5a4ec804339a81f326d936297b6d0c20bba432c3e2d851d2
+  metadata.gz: f45c2c850cfd4b5551aab3608bc23a315c220c4e29f808e7cfc7889858b3b0cf
+  data.tar.gz: 4b53ce7fb3a47bcda9f9720696efd76d0c92c66cecd9abb3f8b03e318968187c
 SHA512:
-  metadata.gz: 58c36a718b50b9f320f101b3d52318ad6557cae9aa80dbb13531a798061a6243156834cc9170a452235be0b330f06772e6d571dc73fa25da2517254fc81850a7
-  data.tar.gz: 903d775a21f5550e0aab21593242308ff3e7ae991fc0df1467376a6a7b210b3c4fec7ae567e074595f48a254ea896f66d9770ebfb8904522cc754e2f7ac14d0b
+  metadata.gz: 7139f7d41bd4dbef2d955db4986aeb19a5ae19794a1677efb30621d9c3e6326e675b7128e46d6d609131c8c31861a3bb2cdce1ee7fca0282ed66c1a5a00b0dd3
+  data.tar.gz: 53df5ac963b3b52bbe02f3fe296a79fa57fb73460cafd3a5261ca7092bdc80f5bce95011522c71cef41dd0635398878f4562450b8010db1e3011a9742c1c76d0

data/README.md

@@ -11,7 +11,12 @@ PandaPal.lti_properties = {oauth_compliant: 'true'}
 PandaPal.lti_environments = { domain: ENV['PROD_DOMAIN'], beta_domain: ENV['BETA_DOMAIN'], test_domain: ENV['TEST_DOMAIN'] }
 PandaPal.lti_custom_params = { custom_canvas_role: '$Canvas.membership.roles' }
 # :user_navigation, :course_navigation for user context and course context endpoints respectively
-PandaPal::stage_navigation(:account_navigation, { enabled: true, text: 'Teacher Reports', visibility: 'admins' })
+PandaPal::stage_navigation(:account_navigation, {
+  enabled: true,
+  # url: :account_index, # Optional if using lti_nav
+  text: 'Teacher Reports',
+  visibility: 'admins',
+})
 ```
 
 Configuration data for an installation can be set by creating a `PandaPal::Organization` record.  Due to the nature of the data segregation, once created, the name of the organization should not be changed (and will raise a validation error).
@@ -28,16 +33,50 @@ Use one of these 6 options in `PandaPal.lti_options` hash.
 5. Leave this property off, and you will get the dynamic host with the root path ('http://appdomain.com/') by default.
 6. If you really do not want this property use the option `launch_url: false` for it to be left off.
 
-# Organization Attributes
-  id: Primary Key
-  name: Name of the organization. Used to on requests to select the tenant
-  key: Key field from CanvasLMS
-  secret: Secret field from CanvasLMS
-  canvas_account_id: ID of the corresponding Canvas account.
-  settings: Hash of settings for this Organization
-  salesforce_id: ID of this organization in Salesforce
+### Task Scheduling
+`PandaPal` includes an integration with `sidekiq-scheduler`. You can define tasks on an Organization class Stub like so:
+```ruby
+# <your_app>/app/models/panda_pal/organization.rb
+require File.expand_path('../../app/models/panda_pal/organization.rb', PandaPal::Engine.called_from)
+
+module PandaPal
+  class Organization
+    # Will invoke CanvasSyncStarterWorker.perform_async() according to the cron schedule
+    scheduled_task '0 15 05 * * *', :identifier, worker: CanvasSyncStarterWorker
+
+    # Will invoke the method 'organization_method' on the Organization
+    scheduled_task '0 15 05 * * *', :organization_method_and_identifier
 
-XML for an installation can be generated by visiting /lti/config in your application.
+    # If you need to invoke the same method on multiple schedules
+    scheduled_task '0 15 05 * * *', :identifier, worker: :organization_method
+
+    # You can also use a block
+    scheduled_task '0 15 05 * * *', :identifier do
+      # Do Stuff
+    end
+
+    # You can use a Proc (called in the context of the Organization) to determine the schedule
+    scheduled_task -> { settings[:cron] }, :identifier
+
+    # You can specify a timezone. If a TZ is not coded and settings[:timezone] is present, it will be appended automatically
+    scheduled_task '0 15 05 * * * America/Denver', :identifier, worker: :organization_method
+
+    # Setting settings[:task_schedules][:identifier] will override the code cron schedule. Setting it to false will disable the Task
+    # :identifer values _must_ be unique, but can be nil, in which case they will be determined by where (lineno etc) scheduled_task is called
+  end
+end
+```
+
+### Organization Attributes
+  `id`: Primary Key
+  `name`: Name of the organization. Used to on requests to select the tenant
+  `key`: Key field from CanvasLMS
+  `secret`: Secret field from CanvasLMS
+  `canvas_account_id`: ID of the corresponding Canvas account.
+  `settings`: Hash of settings for this Organization
+  `salesforce_id`: ID of this organization in Salesforce
+
+XML for an installation can be generated by visiting `/lti/config` in your application.
 
 ### Routing
 
@@ -46,7 +85,7 @@ The following routes should be added to the routes.rb file of the implementing L
 ```ruby
 # config/routes.rb
 mount PandaPal::Engine, at: '/lti'
-lti_nav account_navigation: 'accounts#launch'
+lti_nav account_navigation: 'accounts#launch' # Use lti_nav to provide a custom Launch implementation, otherwise use the url: param of stage_navigation to let PandaPal handle launch.
 root to: 'panda_pal/lti#launch'
 ```
 
@@ -81,9 +120,10 @@ It is also possible to switch tenants by implementing `around_action :switch_ten
 However, it should be noted that calling `switch_tenant` must be used in an `around_action` hook (or given a block), and is only intended to be used for LTI launches, and not subsequent requests.
 
 ### Rake tasks and jobs
-# Delayed Job Support has been removed. This allows each project to assess it's need to handle background jobs.
+**Delayed Job Support has been removed. This allows each project to assess it's need to handle background jobs.**
+
 The Apartment Gem makes it so background jobs need to be run within the current tenant. If using sidekiq, there is a gem that
-does this automatically called apartment-sidkiq. If Delayed Jobs, see how it's done in version 1 of PandaPal.
+does this automatically called `apartment-sidkiq`. If Delayed Jobs, see how it's done in version 1 of PandaPal.
 
 For rake tasks, the current tenant will be set to `public`, and thus special handling must be taken when running the task or queueing jobs as part of it.
 
@@ -125,25 +165,52 @@ Controllers will automatically have access to a number of methods that can be he
 * `save_session` - Saves the session given by `current_session` to the database.
 
 ## Sessions and `current_session`
-A session_key returned by `current_session` is essentially an access token, and while we can't prevent users from sharing if they're so inclined, it should still be kept hidden as much as possible (namely by not including it as a URL param at any time).
-A good way to pass the `session_key` if using ajax or something similar, is to define it as a header in `$.ajaxSetup`.  This is particularly useful if a javascript framework such as React is being utilized.
+Because of the ever-increasing security around `<iframe>`s and cookies, a custom session implementation has been rolled into `PandaPal`.
+The implementation is mostly passive, but requires some changes and caveats as opposed to the native Rails implementation.
 
-PandaPal provides a number of ways to find a session, shown in the example below
+The current session object can be accessed from any controller using `current_session`. This object isn't the actual data container (as `session` _is_ in Rails).
+Session data can be accessed and modified using `current_session.data[:key]` or `current_session_data[:key]`.
 
-```ruby
-def session_key
-  params[:session_key] || session_key_header || flash[:session_key] || session[:session_key]
-end
+Because cookies are unreliable, it becomes the responsibility of the LTI developer to ensure that a custom "cookie" is passed to the frontend with each response
+and returned to the backend with each request, otherwise the backend won't be able to access the current session. There are a few ways to do this.
 
-def session_key_header
-  if match = request.headers['Authorization'].try(:match, /token=(.+)/)
-    match[1]
-  end
-end
+Generally, the method for passing the session "cookie" to the frontend looks something like:
+```html
+<meta name="session_key" content="<%= current_session.session_key %>">
+```
+
+### Returning to the backend
+The `session_key` can be passed to the backend in multiple ways:
+1. (Recommended) Via the `Authorization` Header (usually defining it as a default in your AJAX/XHR/`fetch` library):
+  ```http
+  Authorization: token=SESSION_KEY_HERE
+  ```
+2. Via a `session_key` parameter in a `POST` request (Useful for native HTML `<form>`s).
+3. (Used for Dev, but not highly discouraged in Prod) via a `GET`/URL Query parameter: `?session_key=SESSION_KEY_HERE`.
+
+The `session_key` does not contain any secrets itself, so it is safe to pass to the frontend, but it is encouraged to keep it away from the
+end-user as much as possible because it should not be shared.
+
+### Redirecting and Multi-Page Applications
+Special instructions must be followed when using `link_to` or `redirect_to` to ensure that the Session is passed correctly:
+
+Add a `session_token:` (notice the use of _`_token`_ as opposed to _`_key`_!) parameter when using `link_to` or `redirect_to`:
+```ruby
+  link_to "Link Name", somewhere_else_path(session_token: link_nonce)
+  redirect_to somewhere_else_path(session_token: link_nonce)
+```
+You can also use the `redirect_with_session_to` helper, which will automatically add `organization_id:` and `session_token:` params:
+```ruby
+  redirect_with_session_to :somewhere_else_path, other_param: 1
 ```
+For each request (not each call), `link_nonce` generates a nonce and stores it in the Session. The generated value can be used
+for at-most-one future request. This means that browser back-forward navigation **will not work** (if it actually ever worked for
+iframe-based LTIs in the first place).
 
 ### Persisting the session
-In order to reduce the number of sessions saved to the database, a session should only be saved if data has been added to it.  A good way to accomplish this is to add `append_after_action :save_session, if: proc { session_changed? }` to the application_controller.rb
+The session is automatically saved using an `after_action` callback. This callback is poised to run last, but if that causes issues
+(eg some other callback running afterwards and needing to modify the session), `skip_after_action :auto_save_session` can be used
+and a custom implementation can be supplemented.
 
 ### Session cleanup
 Over time, the sessions table will become bloated with sessions that are no longer active.
@@ -151,11 +218,6 @@ As such, `rake panda_pal:clean_sessions` should be run periodically to clean up
 
 ## Organizations and `current_organization`
 Similar to `current_session`, `current_organization` can be returned with a number of methods, shown below
-```ruby
-def organization_key
-  params[:oauth_consumer_key] || params[:organization_id] || current_session_data[:organization_key] || session[:organization_key]
-end
-```
 
 ## Security
 
@@ -179,56 +241,62 @@ It can be overridden on a action-by-action basis by using `skip_before_action`.
 skip_before_action :forbid_access_if_lacking_session, only: :launch
 ```
 
-### Upgrading to version 3
-
-Before upgrading save existing settings somewhere safe in case you need to
-restore them for whatever reason.
-
-panda_pal v3 introduces an encrypted settings hash.  This should provide more security in the case where a
-customer may have gained access to Organization information in the database.  Settings cannot be decrypted
-without knowing the secret decryption key.  For panda_pal, we are relying on the secret_key_base to be set
-(typically in config/secrets.yml), if that is not available we are falling back to directly use
-ENV['SECRET_KEY_BASE'].  For production environments, config/secrets.yml should not have a plain-text secret,
-it should be referencing an ENV variable.  Make sure your secret is not plain-text committed to a repository!
-
-The secret key is used to encrypt / decrypt the settings hash as necessary.
-
-Before upgrading to version 3, you should confirm that the secret key is set to a consistent value (if the
-value is lost your settings will be hosed).
-
-You should also rollback any local encryption you have done on the settings hash.  The settings hash
-should just be plainly visible when you upgrade to V3.  Otherwise the panda_pal migrations will
-probably fail.
-
-Once you have upgraded your gem, you will need to run migrations.  Before doing that, I would store off your
-unencrypted settings (just in case).
-
-`rake db:migrate`
-
-If all goes well, you should be set!  Log into console, and verify that you can still access settings:
-
-`PandaPal::Organization.first.settings`
-
-should show unencrypted settings in your console.
-
-If anything goes wrong, you should be able to rollback the change:
-
-`rake db:rollback STEP=2`
-
-If you need to give up on the change, just make sure to change your gem version for panda_pal to be < 3.
+### Secure Headers
+PandaPal bundles the `secure_headers` Gem and provides a default config. The PandaPal default works for really basic apps, but you may need to provide
+a custom configuration. This can be done by creating a `secure_headers.rb` initializer in you App like so:
+```ruby
+SecureHeaders::Configuration.default do |config|
+  PandaPal::SecureHeaders.apply_defaults(config) # Optional, but recommended
+  # ...
+end
+```
 
-### Validating settings in your LTI.
+## Validating settings in your LTI.
 
 You can specify a structure that you would like to have enforced for your settings.
 
-In your panda_pal initializer (i.e. config/initializers/panda_pal.rb or config/initializers/lti.rb)
+In your panda_pal initializer (i.e. `config/initializers/panda_pal.rb` or `config/initializers/lti.rb`)
 
 You can specify options that can include a structure for your settings.  If specified, PandaPal will
 enforce this structure on any new / updated organizations.
 
+```ruby
+PandaPal.lti_options = {
+  title: 'LBS Gradebook',
+  settings_structure: {
+    allow_additional: true, # Allow additional properties that aren't included in the :properties Hash.
+    allow_additional: { type: 'String' }, # You can also set :allow_additional to a settings specification that will be used to validate each additional setting
+    validate: ->(value, spec, **kwargs) {
+      # kwargs currently includes:
+      #   :errors => [An array to push errors to]
+      #   :path => [An array representation of the current path in the settings object]
+
+      # To add errors, you may:
+      # Push strings to the kwargs[:errors] Array:
+      kwargs[:errors] << "Your error message at <path>" unless value < 10
+      # Or return a string or string array:
+      value.valid? ? nil : "Your error message at <path>" # <path> will be replaced with the actual path that the error occurred at
+    },
+    properties: {
+      canvas_api_token: { type: 'String', required: true, },
+      catalog: { # :validate, :allow_additional, :properties keys are all supported at this level as well
+        type: 'Hash',
+        required: false,
+        validate: -> (*args) {},
+        allow_additional: false,
+        properties: {
+
+        },
+      }
+    }
+  },
+}
+```
+
+#### Legacy Settings Structure:
 Here is an example options specification:
 
-```
+```ruby
 PandaPal.lti_options = {
   title: 'LBS Gradebook',
   settings_structure: YAML.load("
@@ -271,9 +339,41 @@ This is determined by `PandaPal.lti_options[:platform]`.
 Set this to `platform: 'canvas.instructure.com'` (default)
 OR `platform: 'bridgeapp.com'`
 
-### Safari Support
+## Development:
+### Running Specs:
+Initialize the Specs DB:
+`cd spec/dummy; bundle exec rake db:drop; bundle exec rake db:create; bundle exec rake db:schema:load`
+Then `bundle exec rspec`
 
-Safari is weird, and you'll potentially run into issues getting `POST` requests to properly validate CSRF if you don't do the following:
+## Safari Support
+Safari is weird (it blocks cookies in `<iframe>`s unless the site has set a cookie _outside_ of an `<iframe>` first), and you'll run into
+issues with Rails-native Sessions and CSRF because of that.
+
+This means that safari will likely refuse to send info about your rails session
+back to the LTI, and the application will start up a new session each time the
+browser navigates.  This likely means a new session each time the LTI launches.
+
+### PandaPal 5
+It has been a constant struggle to force safari to store and allow
+access to a rails session while the application is embedded in Canvas.
+
+As of PandaPal 5, a session cookie is no longer required by panda_pal.
+
+See the Section on [Sessions and `current_session`](#sessions-and-current_session)
+
+You will want to watch out for a few scenarios:
+1) Make sure you are using `redirect_with_session_to` if you need to redirect
+   and have your PandaPal session_key persisted server side.
+2) Use the `Authorization` header with `token={session_key}` to send your
+   PandaPal session info into api calls.
+3) If you use `link_to` and navigate in your LTI (apps that are not single page)
+   make sure you include the `link_nonce` like so: 
+    ```ruby
+      link_to "Link Name", somewhere_else_path(session_token: link_nonce)
+    ```
+
+### Previous Safari Instructions
+Safari is weird and you'll potentially run into issues getting `POST` requests to properly validate CSRF if you don't do the following:
 
 - Make sure you have both a `launch` controller and your normal controllers. The `launch` controller should call `before_action :validate_launch!` and then redirect
   to your other controller.
@@ -281,28 +381,47 @@ Safari is weird, and you'll potentially run into issues getting `POST` requests
 
 This will allow `PandaPal` to apply an iframe cookie fix that will allow CSRF validation to work.
 
+## Migrating Major Versions
 
-### PandaPal 5
+### Upgrading to version 3
 
-It has been a constant struggle to force safari to store and allow
-access to a rails session while the application is embedded in Canvas.
+Before upgrading save existing settings somewhere safe in case you need to
+restore them for whatever reason.
+
+panda_pal v3 introduces an encrypted settings hash.  This should provide more security in the case where a
+customer may have gained access to Organization information in the database.  Settings cannot be decrypted
+without knowing the secret decryption key.  For panda_pal, we are relying on the secret_key_base to be set
+(`typically in config/secrets.yml`), if that is not available we are falling back to directly use
+`ENV['SECRET_KEY_BASE']`.  For production environments, `config/secrets.yml` should not have a plain-text secret,
+it should be referencing an ENV variable.  Make sure your secret is not plain-text committed to a repository!
 
-As of PandaPal 5, a persistent session is no longer required by panda_pal.
+The secret key is used to encrypt / decrypt the settings hash as necessary.
 
-This means that safari will likely refuse to send info about your rails session
-back to the LTI, and the application will start up a new session each time the
-browser navigates.  This likely means a new session each time the LTI launches.
+Before upgrading to version 3, you should confirm that the secret key is set to a consistent value (if the
+value is lost your settings will be hosed).
 
-You will want to watch out for a few scenarios:
+You should also rollback any local encryption you have done on the settings hash.  The settings hash
+should just be plainly visible when you upgrade to V3.  Otherwise the panda_pal migrations will
+probably fail.
 
-1) Make sure you are using "redirect_with_session_to" if you need to redirect
-   and have your PandaPal session_key persisted server side.
-2) Use the "Authorization" header with "token={session_key}" to send your
-   PandaPal session info into api calls.
-3) If you use link_to and navigate in your LTI (apps that are not single page)
-   make sure you include an encrypted_session_key parameter in your links.
+Once you have upgraded your gem, you will need to run migrations.  Before doing that, I would store off your
+unencrypted settings (just in case).
 
-# Upgrading from PandaPal 4 to 5:
+`rake db:migrate`
+
+If all goes well, you should be set!  Log into console, and verify that you can still access settings:
+
+`PandaPal::Organization.first.settings`
+
+should show unencrypted settings in your console.
+
+If anything goes wrong, you should be able to rollback the change:
+
+`rake db:rollback STEP=2`
+
+If you need to give up on the change, just make sure to change your gem version for panda_pal to be < 3.
+
+### Upgrading from PandaPal 4 to 5:
 
 If your tool is setup according to a pretty standard pattern (see pace_plans,
 canvas_group_enrollment, etc), you shouldn't have to do anything to upgrade.
@@ -312,7 +431,7 @@ using "redirect_with_session_to".
 
 Here is an example launch / account controller setup, assuming an account launch.
 
-```
+```ruby
 class LaunchController < ApplicationController
   # We don't verify CSRF on launch because the LTI launch is done via a POST
   # request, and Canvas wouldn't know anything about the CSRF
@@ -339,4 +458,3 @@ class AccountController < ApplicationController
   end
 end
 ```
-

data/app/controllers/panda_pal/lti_controller.rb

@@ -2,23 +2,5 @@ require_dependency "panda_pal/application_controller"
 
 module PandaPal
   class LtiController < ApplicationController
-    def tool_config
-      if PandaPal.lti_environments.empty?
-        render plain: 'Domains must be set in lti_environments'
-        return
-      end
-      platform = PandaPal.lti_options.delete(:platform) || 'canvas.instructure.com'
-      request_url = "#{request.scheme}://#{request.host_with_port}"
-      case platform
-      when 'canvas.instructure.com'
-        xml_config = LtiXml::CanvasPlatform.new(platform, request_url, main_app)
-      when 'bridgeapp.com'
-        xml_config = LtiXml::BridgePlatform.new(platform, request_url, main_app)
-      else
-        render plain: 'platform must be set under lti_options'
-        return
-      end
-      render xml: xml_config.xml
-    end
   end
 end

data/app/controllers/panda_pal/lti_v1_p0_controller.rb

@@ -0,0 +1,34 @@
+require_dependency "panda_pal/application_controller"
+
+module PandaPal
+  class LtiV1P0Controller < ApplicationController
+    def launch
+      current_session_data.merge!({
+        lti_version: 'v1p0',
+        lti_launch_placement: params[:launch_type],
+        launch_params: params.to_unsafe_h,
+      })
+
+      redirect_with_session_to(:"#{LaunchUrlHelpers.launch_route(params[:launch_type])}_url", route_context: main_app)
+    end
+
+    def tool_config
+      if PandaPal.lti_environments.empty?
+        render plain: 'Domains must be set in lti_environments'
+        return
+      end
+      platform = PandaPal.lti_options.delete(:platform) || 'canvas.instructure.com'
+      request_url = "#{request.scheme}://#{request.host_with_port}"
+      case platform
+      when 'canvas.instructure.com'
+        xml_config = LtiXml::CanvasPlatform.new(platform, request_url, main_app)
+      when 'bridgeapp.com'
+        xml_config = LtiXml::BridgePlatform.new(platform, request_url, main_app)
+      else
+        render plain: 'platform must be set under lti_options'
+        return
+      end
+      render xml: xml_config.xml
+    end
+  end
+end