nulogy_sso 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4758a2972294221b9dc3fc1bcc3e6cc6bd6b08fb62649c42473947733eac8a26
-  data.tar.gz: 3c367990340d32e800658cb5893e50b239e72b7e647b5e14e7d48eddf58ed50c
+  metadata.gz: 228ee96856caa782a84562d241a407a995eff6f036e143be561f0bbc0ad762ea
+  data.tar.gz: 0bfa85d89f0df4fc65d543737cf7f9f5f28d3617702b1503558b8239b0db2362
 SHA512:
-  metadata.gz: d78af9ca9ae3db0346c647841a132fbcc49b07849934e84b205fa6742d1f7baffe8ae49c842715a9d327291577adcdd1eb3b8f835544798d27f685e6ce1f0fc0
-  data.tar.gz: '0927826539422b8428f4d5c2956b40dbc291d7e558dbe009579cb32468418bfaa24239228550c4d40aefd9b298edf5ac97a78c46d288d7d034849619e393bbe4'
+  metadata.gz: a5afdd2da157f46ab113a271fa605bd1265a86ba733ef7012e0b4106e9ca9b287ce74dc56c36e5aa45496a9a3ed74e97c80c92a0472cf312a52944f75cbbd297
+  data.tar.gz: fd869720b8d14f1e6666888436b243879127fbe229531605b40db32522f9f548d3af607f733aacf5c8cc8c7cdea85fcebbe04607a59b96078c83d9bd7179c421

data/README.md

@@ -30,15 +30,20 @@ get "logout", to: redirect("sso/logout")
 
 The engine now needs to be configured. First create a YAML config file, perhaps named `config/auth_sso.yml`, to configure your app's Auth0 settings. This assumes that the necessary Auth0 applications have been created in the correct Auth0 tenants. The [CPI auth_sso.yml file](https://github.com/nulogy/Common-Platform-Interface/blob/master/config/auth_sso.yml) is a good starting place.
 
-With that available, you can configure the engine with an initializer file. This is where _NulogySSO_ can be customized according to your application's needs. Put this code into `config/initializers/nulogy_sso.rb`, with the appropriate modifications implemented:
+With that available, you can configure the engine with an initializer file. This is where _NulogySSO_ can be customized according to your application's needs. Put the below code into `config/initializers/nulogy_sso.rb`, with the appropriate modifications implemented. For `auth_config`, refer to [nulogy_sso.rb](lib/nulogy_sso.rb) for a list of required keys and [auth_sso.yml](spec/dummy/config/auth_sso.yml) for an example config file.
 
 ```ruby
-# Compiles config/auth_sso.yml into a Ruby object
+# Compiles config/auth_sso.yml into a Ruby object. An error is thrown if required keys are missing.
+# See lib/nulogy_sso.rb for required keys.
 NulogySSO.auth_config = Rails::Application.config_for(:auth_sso)
-# Return the user matching the provided email
+
+# Return the user matching the provided email, or nil if not found.
 NulogySSO.find_user_by_email = ->(email) { nil } 
-# Return a boolean to indicate if the Auth0 user is valid for this app, or true if this step is not necessary
-NulogySSO.validate_user = ->(user) { true } 
+
+# Handle errors from the SSO authentication flow, according to the app's design.
+# This includes internal errors from the Auth0 gem (ie, token signature mismatch) and no user from the app DB matching the email from the JWT.
+# The controller is passed as an argument to give the handler access to the "controller context", which is useful for tasks such as rendering a view.
+NulogySSO.handle_sso_error = ->(controller) { } 
 ```
 
 The app is now ready to authenticate a user with Auth0! With NulogyAuth and Auth0, the user's identity is maintained across requests (and apps!) via a [JWT](https://auth0.com/docs/jwt) stored as a browser cookie. Add this code to the `ApplicationController`:
@@ -51,7 +56,7 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-As an added bonus, NulogySSO also emulates the common Devise pattern of making the current User's user model object available via `current_user`. This is made available through inclusion of `ControllerHelper`.
+As an added bonus, NulogySSO also emulates the common Devise pattern of making the current User's user model object available via `current_user`. This is made available through including `ControllerHelper`.
 
 ## Development
 
@@ -88,3 +93,4 @@ This project follows [Semver Versioning](https://semver.org/). Please add an ent
 * Buildkite pipeline
 * Rubocop
 * Rake install task (ie, generate required files automatically, instead of requiring a heavy amount of manual work to integrate nulogy_sso into a Rails app)
+* Add additional hooks, as necessitated by unique use cases for new apps using this engine

data/app/controllers/nulogy_sso/{auth_controller.rb → authentication_controller.rb}

@@ -3,7 +3,9 @@
 require "auth0"
 
 module NulogySSO
-  class AuthController < ActionController::Base
+
+  # This controller adds routes to power SSO authentication when this engine is mounted into a Rails app.
+  class AuthenticationController < ActionController::Base
     include Auth0::Api::AuthenticationEndpoints
     include Auth0::Mixins::HTTPProxy
 
@@ -53,7 +55,7 @@ module NulogySSO
     delegate :auth_config, to: :NulogySSO
 
     def sso_error
-      render status: :forbidden, template: "sso_error"
+      NulogySSO.handle_sso_error.call(self)
     end
 
     def authenticator

data/app/services/nulogy_sso/authenticator.rb

@@ -10,14 +10,9 @@ module NulogySSO
       jwks_url: "#{NulogySSO.auth_config.base_uri}/.well-known/jwks.json"
     )
 
-    def initialize(
-      verifier: ACCESS_TOKEN_VERIFIER,
-        find_user_by_email: NulogySSO.find_user_by_email,
-        validate_user: NulogySSO.validate_user
-    )
+    def initialize(verifier: ACCESS_TOKEN_VERIFIER, find_user_by_email: NulogySSO.find_user_by_email)
       @verifier = verifier
       @find_user_by_email = find_user_by_email
-      @validate_user = validate_user
     end
 
     # Authorizes the provided JWT, ensuring that a valid user can be associated to the token
@@ -27,12 +22,13 @@ module NulogySSO
       return on_invalid_token.call if access_token.nil?
 
       user = fetch_user(access_token)
-      return on_invalid_token.call if user.blank? || !validate_user.call(user)
+      return on_invalid_token.call if user.blank?
 
       on_success.call(access_token)
     end
 
-    # Returns the authenticated user that matches the provided JWT, or nil if the user cannot be authenticated
+    # Returns the authenticated user that matches the provided JWT, or nil if the token is invalid
+    # or no such user can be found.
     def authenticated_user(raw_access_token)
       access_token = decoded_validated_access_token(raw_access_token)
 
@@ -43,7 +39,7 @@ module NulogySSO
 
     private
 
-    attr_reader :verifier, :find_user_by_email, :validate_user
+    attr_reader :verifier, :find_user_by_email
 
     def decoded_validated_access_token(raw_access_token)
       if raw_access_token.present? && verifier.verify(raw_access_token).valid?

data/config/routes.rb

@@ -1,5 +1,5 @@
 NulogySSO::Engine.routes.draw do
-  get "login", to: "auth#login"
-  get "logout", to: "auth#logout"
-  get "code", to: "auth#code"
+  get "login", to: "authentication#login"
+  get "logout", to: "authentication#logout"
+  get "code", to: "authentication#code"
 end

data/lib/nulogy_sso/controller_helper.rb

@@ -20,13 +20,6 @@ module NulogySSO
 
       @current_user = Authenticator.new.authenticated_user(raw_token)
       return redirect_to nulogy_sso.login_path if @current_user.blank?
-      return render status: :forbidden, template: "sso_error" unless valid_user?(@current_user)
-    end
-
-    private
-
-    def valid_user?(user)
-      NulogySSO.validate_user.call(user)
     end
   end
 end

data/lib/nulogy_sso/engine.rb

@@ -1,3 +1,10 @@
+# frozen_string_literal: true
+
+# List all files that should be automatically loaded for apps using the Engine here (besides files in app/)
+# There are multiple ways to accomplish this via autoloading or eagerloading,
+# but using `require` seems to be the simplest, least-error-prone way.
+require "nulogy_sso/controller_helper"
+
 module NulogySSO
   class Engine < ::Rails::Engine
     isolate_namespace NulogySSO
@@ -5,13 +12,6 @@ module NulogySSO
     # Load all gems in the gemspec, as opposed to explicit require calls
     Bundler.require(*Rails.groups)
 
-    config.autoload_paths << File.expand_path("lib/nulogy_sso/controller_helper", __dir__)
-
-    # Instruct apps using Sprockets to include assets from NulogySSO
-    initializer "nulogy_sso.assets.precompile" do |app|
-      app.config.assets.precompile += ["nulogy_sso/sso_error.css", "nulogy_sso/favicon.png"]
-    end
-
     config.after_initialize do
       if NulogySSO.auth_config.blank?
         raise "Missing auth_config config object. Consider using config_for() to load a YAML config file."
@@ -21,8 +21,8 @@ module NulogySSO
         raise "Missing find_user_by_email config lambda."
       end
 
-      if NulogySSO.validate_user.blank?
-        raise "Missing validate_user config lambda."
+      if NulogySSO.handle_sso_error.blank?
+        raise "Missing handle_sso_error config lambda."
       end
     end
   end

data/lib/nulogy_sso/version.rb

@@ -1,3 +1,3 @@
 module NulogySSO
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/nulogy_sso.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require "nulogy_sso/engine"
-require "nulogy_sso/controller_helper"
 require "immutable-struct"
 
 module NulogySSO
   # Config variables for the engine
-  mattr_accessor :auth_config, :find_user_by_email, :validate_user
+  mattr_accessor :auth_config, :find_user_by_email, :handle_sso_error
 
   # Public Constants
   JWT_EMAIL_KEY = "https://nulogy.net/email"

data/spec/dummy/config/application.rb

@@ -10,7 +10,7 @@ require "action_controller/railtie"
 # require "action_mailer/railtie"
 require "action_view/railtie"
 require "action_cable/engine"
-require "sprockets/railtie"
+# require "sprockets/railtie"
 # require "rails/test_unit/railtie"
 
 Bundler.require(*Rails.groups)
@@ -32,10 +32,10 @@ module Dummy
     # the framework and any gems in your application.
 
     # Load required NulogySSO config so that the dummy can boot up without error.
-    # These functions are based on the dummy app User class, mostly used for testing.
+    # These functions are mostly used for testing.
     NulogySSO.auth_config = config_for(:auth_sso)
     NulogySSO.find_user_by_email = ->(email) { User.find_by(email: email) }
-    NulogySSO.validate_user = ->(user) { user.active? }
+    NulogySSO.handle_sso_error = ->(controller) { controller.render plain: "An SSO error has occurred :(" }
   end
 end