Allow OmniAuth Setup Phase to be configured (#76)

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

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,30 +23,32 @@ class Engine < ::Rails::Engine
     initializer 'RpiAuth.add_middleware' do |app| # rubocop:disable Metrics/BlockLength
       next unless RpiAuth.configuration
 
+      openid_connect_options = {
+        name: :rpi,
+        setup: RpiAuth.configuration.setup,
+        issuer: RpiAuth.configuration.issuer,
+        scope: RpiAuth.configuration.scope,
+        callback_path: CALLBACK_PATH,
+        response_type: RpiAuth.configuration.response_type,
+        client_auth_method: RpiAuth.configuration.client_auth_method,
+        client_options: {
+          identifier: RpiAuth.configuration.auth_client_id,
+          secret: RpiAuth.configuration.auth_client_secret,
+          scheme: RpiAuth.configuration.token_endpoint.scheme,
+          host: RpiAuth.configuration.token_endpoint.host,
+          port: RpiAuth.configuration.token_endpoint.port,
+          authorization_endpoint: RpiAuth.configuration.authorization_endpoint,
+          token_endpoint: RpiAuth.configuration.token_endpoint,
+          jwks_uri: RpiAuth.configuration.jwks_uri,
+          redirect_uri: URI.join(RpiAuth.configuration.host_url, CALLBACK_PATH)
+        },
+        extra_authorize_params: { brand: RpiAuth.configuration.brand },
+        allow_authorize_params: [:login_options],
+        origin_param: 'returnTo'
+      }
+
       app.middleware.use OmniAuth::Builder do
-        provider(
-          :openid_connect,
-          name: :rpi,
-          issuer: RpiAuth.configuration.issuer,
-          scope: RpiAuth.configuration.scope,
-          callback_path: CALLBACK_PATH,
-          response_type: RpiAuth.configuration.response_type,
-          client_auth_method: RpiAuth.configuration.client_auth_method,
-          client_options: {
-            identifier: RpiAuth.configuration.auth_client_id,
-            secret: RpiAuth.configuration.auth_client_secret,
-            scheme: RpiAuth.configuration.token_endpoint.scheme,
-            host: RpiAuth.configuration.token_endpoint.host,
-            port: RpiAuth.configuration.token_endpoint.port,
-            authorization_endpoint: RpiAuth.configuration.authorization_endpoint,
-            token_endpoint: RpiAuth.configuration.token_endpoint,
-            jwks_uri: RpiAuth.configuration.jwks_uri,
-            redirect_uri: URI.join(RpiAuth.configuration.host_url, CALLBACK_PATH)
-          },
-          extra_authorize_params: { brand: RpiAuth.configuration.brand },
-          allow_authorize_params: [:login_options],
-          origin_param: 'returnTo'
-        )
+        provider(:openid_connect, openid_connect_options)
 
         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

spec/support/omniauth.rb

@@ -1,3 +1,14 @@
 # frozen_string_literal: true
 
 require 'omniauth'
+
+RSpec.configure do |config|
+  config.around do |example|
+    original_value = OmniAuth.config.test_mode
+    begin
+      example.run
+    ensure
+      OmniAuth.config.test_mode = original_value
+    end
+  end
+end