canvas_lti_third_party_cookies 0.3.3 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d622f96431568706549721c48a8cab10edd7f21790f739d612f2af1e649a686
-  data.tar.gz: b0a008358a161f117a9c828975ac40e642a93af253cbd34b4ae3f2abf4890efb
+  metadata.gz: 153e4d2eaa313e523dcfbab4139c2ea938a0969261d7c69ec15bb3028c2ab506
+  data.tar.gz: 1b0808375ebfeb54e896183db7a769b40f32475d503a184af43300629da6f732
 SHA512:
-  metadata.gz: 076670fa98327844ceee397d68e346179d326839b831454b80c94e68a1866c43a58873d9b1c1d6032258c21e0be38d44164bd831f7a4287d7a8d9daf519688ee
-  data.tar.gz: 4d70af2daa01fc4fb262c01c186f581c81db4fe32c3bf7c025050fe4d9e149bd70c3430e7ce1f8f05cfaab245e3a4df4adae7a09b5b42ba6a13370dca237ed74
+  metadata.gz: 186d3c0358b1f72fceee476b794ee3f87332e111a4cdfc5295fd6a4d529f8ceac8770cf9aaf3f57c9b0207aba66b9d98ac1b4e22ab9f83b7e6ead6a8fa539da7
+  data.tar.gz: 5cc9890e6df93bcf9cd824617758070ee69ff53428de2bf1c69f0e8f44b89fe50f4309322ca211a961d3adfea90e393eab6d6fd03bad1517e879a5fb9e82df4b

data/README.md

@@ -1,70 +1,143 @@
 # canvas_lti_third_party_cookies
 
-Safari blocks all 3rd-party cookies by default, which breaks LTI tools that rely on setting cookies when launched in an iframe. Instead, it exposes a new API for getting user-permitted access to set cookies from an iframe, which works though requires jumping through some fun hoops.
-See this article for a detailed explanation: https://community.canvaslms.com/t5/Developers-Group/Safari-13-1-and-LTI-Integration/ba-p/273051
+Safari blocks all 3rd-party cookies by default, which breaks LTI tools that rely on setting cookies when launched in an iframe. Other browsers will soon follow suit. Instead, Safari exposes a new API for getting user-permitted access to set cookies from an iframe, which unfortunately doesn't completely work for LTI use cases.
+See this article for a detailed explanation of the Storage Access API and previous attempts to launch LTI tools in Safari: https://community.canvaslms.com/t5/Developers-Group/Safari-13-1-and-LTI-Integration/ba-p/273051
 
-This gem wraps the Safari cookie dance in a Rails engine that can be easily used with one before_action callback. It is built for use with Canvas,
-which is responsible for some parts of this cookie dance, including launching the tool in a full-window 1st-party context, and providing a
-redirect url for the relaunch after the full-window launch is complete. 
+The current workaround that this gem implements is to relaunch the tool in a new tab, new window, or popup window, where it can set first-party cookies to its heart's content. The relaunch occurs during the login request, so the tool is entirely in control, and no other parts of the LTI launch flow are modified.
 
-This gem won't work without being launched from Canvas, or a Tool Consumer that implements the same `window.postMessage` listener as Canvas
-does here: https://github.com/instructure/canvas-lms/blob/master/public/javascripts/lti/post_message/requestFullWindowLaunch.js
+## Installation
+Add this line to your application's Gemfile:
 
-## Usage
+```ruby
+# Set 3rd party cookies in Safari
+gem 'canvas_lti_third_party_cookies'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
 
-Choose the Rails controller action that's used to launch your tool and set cookies. Set the before_action callback
-below to run on that action, and pass the data needed.
+Since this gem includes some static assets (JS, CSS, images), you will need to make sure
+that your application runs the `rake assets:precompile` task at some point during its
+build process. Most Rails applications will be running that already, either directly or
+as part of the `rake webpacker:compile` task.
 
-* the `launch_url` parameter is required, which should be the route
-  that launches the tool.
-* the `launch_params` parameter is optional, and should contain
-  all needed query parameters that the tool requires to launch.
-* the `launch_data` parameter is optional, and should contain
-  all needed form data that the tool requires to launch.
+Neglecting to precompile assets will result in runtime errors when users try to launch
+your LTI tool.
 
-Usually, only query parameters *or* form data is needed, not both.
+## Usage
 
+Choose the Rails controller action that's used to handle tool authentication requests.
+Set the before_action callback below to run on that action, and pass the data needed.
+
+* `redirect_url` (required): the authorization redirect URL to continue the login flow
+* `redirect_data` (required): all form data required for the authorization redirect, which
+the previous login render call should have included in a form tag.
+* `window_type`: (optional) Set to `:new_window` to open the tool in a
+new tab or window, or to `:popup` to open in a popup window.
+Defaults to `:new_window`.
+* `width`: (optional) The width the popup window should be, in px. User
+has the discretion to ignore this. Only valid with window_type: popup.
+Defaults to 800px.
+* `height`: (optional) The height the popup window should be, in px. User
+has the discretion to ignore this. Only valid with window_type: popup.
+Defaults to 600px.
+
+example:
 ```ruby
-include CanvasLtiThirdPartyCookies::SafariLaunch
-#...
-before_action -> { 
-  handle_safari_launch(launch_url: action_url, launch_params: { foo: bar }, launch_data: { foo: baz })
-}
+include CanvasLtiThirdPartyCookies::RelaunchOnLogin
+...
+def login
+  state, nonce = create_and_cache_state # handled elsewhere
+  redirect_url = 'http://canvas.instructure.com/api/lti/authorize_redirect'
+  # this data is part of the OIDC Launch Flow as defined here:
+  # https://www.imsglobal.org/spec/security/v1p0/#step-2-authentication-request
+  redirect_data = {
+    scope: 'openid',
+    response_type: 'id_token',
+    response_mode: 'form_post',
+    prompt: 'none',
+    redirect_uri: tool_launch_url, # defined elsewhere
+    client_id: params.require(:client_id),
+    login_hint: params.require(:login_hint),
+    lti_message_hint: params.require(:lti_message_hint),
+    state: state,
+    nonce: nonce
+  }
+
+  relaunch_on_login(redirect_url, redirect_data)
+end
 ```
 
-This will launch the tool multiple times, and also redirect the user back to Canvas when needed. For more information on the detailed tool
-launches, see the comments in `app/controllers/concerns/canvas_lti_third_party_cookies/safari_launch.rb`.
+## Local Development
 
-Note that the tool will be relaunched from within this method once Storage Access is granted and pass all parameters from the previous
-Canvas launch, which will break JWT nonce verification since it will detect the nonce has already been used. 
+To make changes and test them locally, it's possible to install this gem in a local
+LTI tool installation.
 
-To combat this, this gem provides the `should_ignore_nonce?` method so that your tool can ignore the nonce verification for that
-specific launch. Normally, ignoring a duplicate nonce can lead to replay attacks. This method will only return true if the request's
-`Referer` header matches the tool's domain, which only happens in this last internal redirect.
+1. In your tool's Gemfile, add `, path: './cookies'` to the line for this gem.
+2. In your tool's docker-compose.override.yml, add a new volume to link this gem's
+folder to the `./cookies` path. It should look like this:
+```
+volumes:
+  - ./path/to/lti_third_party_cookies:/usr/src/app/cookies
+```
+3. `bundle install` again.
 
-## Installation
-Add this line to your application's Gemfile:
+The same process is possible with non-docker-compose apps, just directly point to the
+gem's folder from your tool's Gemfile.
 
-```ruby
-# Set 3rd party cookies in Safari
-gem 'canvas_lti_third_party_cookies'
+## Testing
+
+### Ruby Tests
+
+The ruby tests use `minitest`, which comes bundled with rails. To run them locally:
+```
+rails test
 ```
 
-And then execute:
-```bash
-$ bundle install
+There is a Docker setup for running tests that's used for CI. To run them in Docker locally:
+```
+docker build -f test/Dockerfile.ruby -t ruby-test .
+docker run --rm ruby-test rails test
 ```
 
-## Testing
+### Javascript Tests
 
-```bash
-$ rails test
+The JS tests are self-contained in the `test/javascripts` folder. To run them locally:
 ```
+cd test/javascripts
+yarn install
+yarn test
+```
+
+There is a Docker setup for running tests that's used for CI. To run them in Docker locally:
+```
+docker build -f test/Dockerfile.node -t node-test .
+docker run --rm node-test yarn test
+```
+
+## i18n
+
+All user-facing strings in this gem are localized and translated into the languages that
+Canvas supports. Any time that any strings are changed, you should make sure this is run:
+```
+rake app:i18nliner:dump
+```
+Then, add `config/locales/generated/en.yml` to your commit.
+
+After making changes to `en.yml`, you will need to push these changes to the
+`instructure-translations` S3 bucket so that the translators can update other locales.
+TODO: the script or Jenkins job to actually push to S3.
+
+Once translators have finished updating other locales, they will notify you, and you can
+pull down the new locale files into `config/locales`, and commit and push them.
+TODO: the script or Jenkins job to pull from S3.
 
 ## Publishing New Versions
 
 1. Bump the version in `lib/canvas_lti_third_party_cookies/version.rb`.
-2. Commit, push, and merge that change.
-3. `rake install`
+2. `rake install`
+3. Commit, push, and merge that change.
 4. `gem push pkg/canvas_lti_third_party_cookies-<version>.gem`
   - note that this will only work if you have access

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 begin
   require 'bundler/setup'
 rescue LoadError