Allow OmniAuth Setup Phase to be configured

The OmniAuth Setup Phase[1] allows for "request-time modification of an
OmniAuth strategy". We're intending to use this in Experience CS so that
we can optionally include the `student` scope[2] to allow students to
login.

The Profile app uses the presence of the `student` scope in the login
request to decide whether to display the student login form (i.e. the
form containing the school code textbox). We want to allow students (as
well as non-students) to login to Experience CS and so need a way of
changing the `scope` accordingly. By default the `scope` is fixed at
Rails initialization time in the `RpiAuth::Engine`[3] but we need to be
able to toggle it at runtime depending on whether user is a student or
not. By utilising OmniAuth's setup phase[2] we can toggle the `scope`
based on something we set in the app (e.g. we might set something in the
session to indicate that we want the student login flow).

I initially added logic in this Gem to add the `student` scope if a
specific value was set in the session but later decided that it should
be up to the consuming apps to use this `setup` phase as they see fit.

[1]: https://github.com/omniauth/omniauth/wiki/Setup-Phase
[2]: https://github.com/RaspberryPiFoundation/documentation/blob/a92f03446a347d2d1acea48c50ea37f15293a9b6/docs/technology/codebases-and-products/accounts/profile-app/custom-oidc-scopes.md#available-custom-scopes
[3]: https://github.com/RaspberryPiFoundation/rpi-auth/blob/b7771ee120254e4c6f2d90c5025be5714daeb542/lib/rpi_auth/engine.rb#L31

Author: chrisroos

lib/rpi_auth/configuration.rb

@@ -18,7 +18,8 @@ class Configuration
                   :scope,
                   :session_keys_to_persist,
                   :success_redirect,
-                  :user_model
+                  :user_model,
+                  :setup
 
     def initialize
       @bypass_auth = false

lib/rpi_auth/engine.rb

@@ -27,6 +27,7 @@ class Engine < ::Rails::Engine
         provider(
           :openid_connect,
           name: :rpi,
+          setup: RpiAuth.configuration.setup,
           issuer: RpiAuth.configuration.issuer,
           scope: RpiAuth.configuration.scope,
           callback_path: CALLBACK_PATH,

spec/dummy/config/initializers/rpi_auth.rb

@@ -1,4 +1,11 @@
 RpiAuth.configure do |config|
+  config.setup = lambda do |env|
+    request = Rack::Request.new(env)
+
+    if custom_scope = request.params['add-custom-scope']
+      env['omniauth.strategy'].options[:scope] += [custom_scope]
+    end
+  end
   config.auth_url = 'http://localhost:9001'
   config.auth_client_id = 'gem-dev'
   config.auth_client_secret = 'secret'

spec/dummy/spec/requests/auth_request_spec.rb

@@ -312,5 +312,35 @@
         end
       end
     end
+
+    describe 'and toggling the scope at runtime' do
+      let(:custom_scope) { 'custom-scope' }
+
+      before do
+        OmniAuth.config.test_mode = false
+      end
+
+      it 'does not append a custom scope' do
+        post '/auth/rpi'
+
+        scopes = extract_scopes_from_redirect_location(response)
+
+        expect(scopes).not_to include(custom_scope)
+      end
+
+      it 'appends a custom scope' do
+        post "/auth/rpi?add-custom-scope=#{custom_scope}"
+
+        scopes = extract_scopes_from_redirect_location(response)
+
+        expect(scopes).to include(custom_scope)
+      end
+
+      def extract_scopes_from_redirect_location(response)
+        location = response.headers['location']
+        params = CGI.parse(URI.parse(location).query)
+        params['scope'].first.split(' ')
+      end
+    end
   end
 end

spec/dummy/spec/requests/foo_request_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe 'Foo' do
+  describe 'POST /auth/rpi' do
+    describe 'On successful authentication' do
+      it 'foo' do
+        post '/auth/rpi?add-custom-scope=true'
+
+        location = response.headers['location']
+        params = CGI.parse(URI.parse(location).query)
+        scopes = params['scope'].first.split(' ')
+
+        expect(scopes).to include('custom-scope')
+      end
+    end
+  end
+end