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 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

@@ -23,10 +23,12 @@ class Engine < ::Rails::Engine
     initializer 'RpiAuth.add_middleware' do |app| # rubocop:disable Metrics/BlockLength
       next unless RpiAuth.configuration
 
+      # rubocop:disable Metrics/BlockLength
       app.middleware.use OmniAuth::Builder do
         provider(
           :openid_connect,
           name: :rpi,
+          setup: RpiAuth.configuration.setup,
           issuer: RpiAuth.configuration.issuer,
           scope: RpiAuth.configuration.scope,
           callback_path: CALLBACK_PATH,
@@ -47,6 +49,7 @@ class Engine < ::Rails::Engine
           allow_authorize_params: [:login_options],
           origin_param: 'returnTo'
         )
+        # rubocop:enable Metrics/BlockLength
 
         OmniAuth.config.on_failure = RpiAuth::AuthController.action(:failure)
 

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