nulogy_sso 0.2.0

checksums.yaml

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

data/README.md

@@ -0,0 +1,90 @@
+# NulogySSO
+
+**This repo is still under heavy initial development and is not ready to be used by any other product besides CPI. This status will be changed very shortly.**
+
+## Installation
+
+This gem is a Rails Engine. It follows best practices [documented here](https://guides.rubyonrails.org/engines.html).
+
+To begin with, add the gem to your Gemfile:
+
+```ruby
+gem "nulogy_sso"
+```
+
+Install the gem:
+
+```sh
+bundle
+```
+
+Routes can now be mounted into your application in `routes.rb` and served up at a specific URI prefix:
+
+```ruby
+mount NulogySSO::Engine, at: "/sso"
+
+# Optional redirects
+get "login", to: redirect("sso/login")
+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:
+
+```ruby
+# Compiles config/auth_sso.yml into a Ruby object
+NulogySSO.auth_config = Rails::Application.config_for(:auth_sso)
+# Return the user matching the provided email
+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 } 
+```
+
+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`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include NulogySSO::ControllerHelper
+  before_action :authenticate_sso_user
+  # ...
+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`.
+
+## Development
+
+### Setup
+
+```sh
+# Setup Ruby
+rvm install $(cat .ruby-version)
+bundle
+
+# Setup project files
+cp .env.sample .env
+rake app:db:test:prepare
+
+# Launch Docker containers, required for testing
+docker-compose up -d
+```
+
+### Testing
+
+There are multiple helpers made available via the `NulogyAuth::TestUtilities` module. These are helpful for doing things such as grabbing test JWT values and interacting with a [Mockserver](https://github.com/jamesdbloom/mockserver) mock of the Auth0 API.
+
+It is a common use case for a Rails app to switch from Devise-powered authentication to Auth0. Here's a pattern that could be applied around a feature flag (e.g. environment variable) to switch between Devise user authentication test helpers and NulogyAuth test helpers: _(TODO: insert link to CPI `ControllerIntegrationSpecMacros`)_
+
+### Contributing
+
+Feel free to create a PR if you wish to add new functionality to this Engine or detect a bug. A developer on CN1 will review and merge.
+
+This project follows [Semver Versioning](https://semver.org/). Please add an entry into [CHANGELOG.md](./CHANGELOG.md) in your PR. Deployments are done manually on an as-needed basis.
+
+## Roadmap
+
+* Parameterize app name for error page
+* 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)

data/Rakefile

@@ -0,0 +1,22 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "NulogySSO"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/nulogy_sso/sso_error.css

@@ -0,0 +1,214 @@
+/**
+ * Do not edit directly
+ * Generated on Fri, 21 Jun 2019 19:45:11 GMT
+ */
+/* -----------------------------------------
+    ## Default styles
+----------------------------------------- */
+html,
+body {
+  margin: 0;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  color: #011e38;
+  font-family: "IBM Plex Sans", sans-serif;
+  line-height: 1.5;
+}
+
+code {
+  font-family: "IBM Plex Mono", monospace;
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+
+/* -----------------------------------------
+    ## Alerts
+----------------------------------------- */
+.Alert {
+  border-radius: 4px;
+  border-left: 4px solid #216beb;
+  padding: 16px;
+  background: #e1ebfa;
+  display: flex;
+  max-width: 432px;
+}
+.Alert__icon {
+  fill: #216beb;
+}
+.Alert a {
+  color: #011e38;
+}
+
+.Alert__title {
+  margin: 0;
+  font-weight: 600;
+}
+
+.Alert__message {
+  margin-top: 0;
+}
+.Alert__message:last-child {
+  margin-bottom: 0;
+}
+
+.Alert--danger__icon,
+.Alert--success__icon {
+  margin-right: 8px;
+}
+
+.Alert--danger {
+  border-radius: 4px;
+  border-left: 4px solid #cc1439;
+  padding: 16px;
+  background: #fae6ea;
+}
+.Alert--danger__icon {
+  fill: #cc1439;
+}
+.Alert--danger a {
+  color: #011e38;
+}
+
+.Alert--success {
+  border-radius: 4px;
+  border-left: 4px solid #008059;
+  padding: 16px;
+  background: #e9f7f2;
+}
+.Alert--success__icon {
+  fill: #008059;
+}
+.Alert--success a {
+  color: #011e38;
+}
+
+.Alert--warning {
+  border-radius: 4px;
+  border-left: 4px solid #ffbb00;
+  padding: 16px;
+  background: #fcf5e3;
+}
+.Alert--warning__icon {
+  fill: #ffbb00;
+}
+.Alert--warning a {
+  color: #011e38;
+}
+
+/* -----------------------------------------
+    ## Link
+----------------------------------------- */
+.Link {
+  color: #216beb;
+}
+.Link:hover {
+  cursor: pointer;
+  color: #1254c7;
+}
+.Link:focus {
+  outline: none;
+  box-shadow: 0px 0px 5px 0px rgba(33, 107, 235, 0.9);
+}
+
+/* -----------------------------------------
+    ## Error page
+----------------------------------------- */
+.ErrorPage {
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  padding: 16px;
+  padding-top: 24px;
+}
+
+.ErrorPage__body {
+  display: flex;
+  flex-direction: column;
+  flex-grow: 1;
+}
+
+.ErrorPage__container {
+  max-width: 432px;
+  margin: 0 auto;
+}
+
+.ErrorPage__header {
+  text-align: center;
+  margin-top: 16px;
+  margin-bottom: 40px;
+}
+
+.ErrorPage__logout {
+  margin-right: auto;
+  margin-left: auto;
+  margin-top: 30px;
+}
+@media screen and (min-width: 768px) {
+  .ErrorPage__header {
+    margin-top: 80px;
+  }
+}
+@media screen and (min-width: 1360px) {
+  .ErrorPage__header {
+    margin: 0;
+  }
+}
+
+.ErrorPage__logo {
+  display: block;
+  margin: 0 auto;
+}
+@media screen and (min-width: 1360px) {
+  .ErrorPage__logo--with-homepage-link {
+    margin-top: -32px;
+  }
+}
+
+.ErrorPage__main {
+  max-width: 432px;
+  margin: 0 auto;
+  text-align: center;
+}
+@media screen and (min-width: 1360px) {
+  .ErrorPage__main {
+    text-align: left;
+  }
+}
+.ErrorPage__main .Alert {
+  text-align: left;
+}
+
+.ErrorPage__footer {
+  border-top: 1px solid #e4e7eb;
+  padding-top: 16px;
+  text-align: center;
+  font-size: 14px;
+  color: #434d59;
+}
+
+.Link--ErrorPage {
+  color: #00438f;
+  display: inline-block;
+  margin-top: 16px;
+}
+
+@media screen and (min-width: 1360px) {
+  .ErrorPage__body {
+    justify-content: center;
+  }
+  .ErrorPage__contents {
+    display: flex;
+    width: 672px;
+    margin: 0 auto;
+    align-items: center;
+  }
+}

data/app/controllers/nulogy_sso/auth_controller.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "auth0"
+
+module NulogySSO
+  class AuthController < ActionController::Base
+    include Auth0::Api::AuthenticationEndpoints
+    include Auth0::Mixins::HTTPProxy
+
+    def initialize
+      # These instance variables have to be set in order for the HTTPProxy mixin to work.
+      @base_uri = auth_config.base_uri
+      @headers = { content_type: "application/json" }
+    end
+
+    def login
+      raw_access_token = cookies[NulogySSO.auth_cookie_key]
+
+      authenticator.validate_token(
+        raw_access_token,
+        on_success: method(:on_authentication_success),
+        on_invalid_token: -> { redirect_to auth_path }
+      )
+    end
+
+    def code
+      code = params.require(:code)
+      begin
+        raw_access_token = token_response(code)["access_token"]
+      rescue Auth0::Exception => e
+        return sso_error
+      end
+
+      authenticator.validate_token(
+        raw_access_token,
+        on_success: method(:on_authentication_success),
+        on_invalid_token: -> { sso_error }
+      )
+    end
+
+    def logout
+      cookies.delete(NulogySSO.auth_cookie_key, domain: :all)
+
+      query_params = {
+        returnTo: auth_config.redirect_uri, # Yes, this must be camelCased
+        client_id: auth_config.client_id
+      }
+      redirect_to "#{auth_config.base_uri}/v2/logout?#{query_params.to_query}"
+    end
+
+    private
+
+    delegate :auth_config, to: :NulogySSO
+
+    def sso_error
+      render status: :forbidden, template: "sso_error"
+    end
+
+    def authenticator
+      @authenticator ||= Authenticator.new
+    end
+
+    def on_authentication_success(access_token)
+      respond_with_cookies(access_token)
+
+      redirect_to params["origin"].presence || auth_config.redirect_uri
+    end
+
+    def token_response(code)
+      exchange_auth_code_for_tokens(
+        code,
+        redirect_uri: auth_config.login_uri,
+        client_id: auth_config.client_id,
+        client_secret: auth_config.client_secret
+      )
+    end
+
+    def respond_with_cookies(access_token_value)
+      cookies[NulogySSO.auth_cookie_key] = {
+        value: access_token_value,
+        domain: :all,
+        expires: 36_000.seconds, # TODO: Fetch this value from the JWT
+        httponly: true,
+        secure: request.ssl?
+      }
+    end
+
+    def auth_path
+      query_params = {
+        audience: auth_config.audience,
+        client_id: auth_config.client_id,
+        response_type: "code",
+        scope: "openid email",
+        redirect_uri: "#{auth_config.login_uri}?origin=#{session[:previous_request_url]}"
+      }
+
+      "#{auth_config.base_uri}/authorize?#{query_params.to_query}"
+    end
+  end
+end

data/app/services/nulogy_sso/authenticator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "auth0_rs256_jwt_verifier"
+
+module NulogySSO
+  class Authenticator
+    ACCESS_TOKEN_VERIFIER = Auth0RS256JWTVerifier.new(
+      issuer: "#{NulogySSO.auth_config.base_uri}/", # Auth0 requires a backslash on the Issuer
+      audience: NulogySSO.auth_config.audience,
+      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
+    )
+      @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
+    def validate_token(raw_access_token, on_success:, on_invalid_token:)
+      access_token = decoded_validated_access_token(raw_access_token)
+
+      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)
+
+      on_success.call(access_token)
+    end
+
+    # Returns the authenticated user that matches the provided JWT, or nil if the user cannot be authenticated
+    def authenticated_user(raw_access_token)
+      access_token = decoded_validated_access_token(raw_access_token)
+
+      return nil if access_token.nil?
+
+      fetch_user(access_token)
+    end
+
+    private
+
+    attr_reader :verifier, :find_user_by_email, :validate_user
+
+    def decoded_validated_access_token(raw_access_token)
+      if raw_access_token.present? && verifier.verify(raw_access_token).valid?
+        return JSON::JWT.decode(raw_access_token, :skip_verification)
+      end
+
+      nil
+    end
+
+    def fetch_user(access_token)
+      email = access_token.fetch(NulogySSO::JWT_EMAIL_KEY)
+      find_user_by_email.call(email)
+    end
+  end
+end

data/app/views/sso_error.html.erb

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <meta http-equiv="X-UA-Compatible" content="ie=edge">
+  <title>Error</title>
+  <%= favicon_link_tag "nulogy_sso/favicon.png" %>
+  <%= stylesheet_link_tag "nulogy_sso/sso_error" %>
+  <link href="https://fonts.googleapis.com/css?family=IBM+Plex+Sans:300,400,500,600&display=swap" rel="stylesheet">
+</head>
+
+<body>
+<div class="ErrorPage">
+  <div class="ErrorPage__body">
+    <div class="ErrorPage__contents">
+      <header class="ErrorPage__header">
+        <svg class="ErrorPage__logo" height="48px" width="200px" viewBox="0 0 133 32"><path fill="#F0B41C" d="M30.6967273,1.13648485 L36.3810909,3.40945455 L36.3810909,23.8758788 C36.3810909,28.2705455 30.9507879,29.0424242 27.2853333,29.5602424 C29.3818182,29.0424242 30.7083636,28.4606061 30.6967273,23.8758788 L30.6967273,5.68436364 L25.0123636,3.40945455 L30.6967273,1.13648485 Z M6.82084848,28.4237576 L6.82084848,15.9204848 C6.82084848,14.6618182 7.76533333,13.238303 8.91151515,12.7476364 L14.7801212,10.2264242 L14.7801212,18.1779394 L20.4644848,21.6048485 C21.6106667,22.1866667 23.8758788,22.2002424 23.8758788,20.4664242 L23.8758788,17.0550303 L21.5990303,15.9166061 L21.5990303,1.56319402e-13 L4.26666667,6.38642424 C1.91030303,7.25333333 3.55271368e-15,9.98593939 3.55271368e-15,12.5071515 L3.55271368e-15,31.2669091 L6.82084848,28.4237576 Z"></path><g transform="translate(43.000000, 0.000000)" fill="#1C68A5"><path d="M5.14521212,24.2224981 L1.33226763e-14,24.2224981 L1.33226763e-14,9.41134654 L4.75151515,9.41134654 L4.75151515,11.8937708 C5.43733518,11.0060378 6.29475204,10.2653615 7.27272727,9.71583139 C8.16188898,9.23817548 9.15699751,8.9920662 10.166303,9.00019502 C11.7333333,9.00019502 12.9221818,9.44948795 13.7328485,10.3480738 C14.5435152,11.2466597 14.9488485,12.5615688 14.9488485,14.2928011 L14.9488485,24.2224981 L9.83078788,24.2224981 L9.83078788,15.7376496 C9.83078788,14.961892 9.67175758,14.3755486 9.35369697,13.9786193 C9.03563636,13.58169 8.56436364,13.3877506 7.93987879,13.3968011 C7.04258586,13.3968011 6.35216162,13.6980536 5.86860606,14.3005587 C5.38505051,14.9030637 5.14391919,15.7803162 5.14521212,16.9323162 L5.14521212,24.2224981 Z"></path><path d="M27.8366061,9 L32.9507879,9 L32.9507879,22.6203636 L28.1992727,24.5190303 L28.1992727,21.6254545 C27.5124636,22.5143219 26.6553593,23.2573653 25.6780606,23.8111515 C24.7938668,24.2845189 23.8048332,24.5279425 22.8019394,24.5190303 C21.2323232,24.5190303 20.0402424,24.0665051 19.225697,23.1614545 C18.4111515,22.256404 18.0025859,20.9408485 18,19.2147879 L18,9 L23.1452121,9 L23.1452121,17.7796364 C23.1452121,18.5553939 23.3042424,19.1443232 23.622303,19.5464242 C23.9403636,19.9485253 24.4116364,20.1482828 25.0361212,20.145697 C25.9411717,20.145697 26.631596,19.8418586 27.1073939,19.2341818 C27.5831919,18.6265051 27.8243232,17.7524848 27.8307879,16.6121212 L27.8366061,9 Z"></path><polygon id="Path" points="38.7151515 24.5546667 36 24.5546667 36 1.088 38.7151515 1.15463195e-13"></polygon><path d="M41,17.0717576 C41,14.7263838 41.7453737,12.7947475 43.2361212,11.2768485 C44.7268687,9.75894949 46.6171313,9 48.9069091,9 C51.1966869,9 53.0869495,9.75894949 54.577697,11.2768485 C56.0684444,12.7947475 56.8138182,14.7263838 56.8138182,17.0717576 C56.8138182,19.4274747 56.0684444,21.3668687 54.577697,22.8899394 C53.0869495,24.4130101 51.1966869,25.1719596 48.9069091,25.1667879 C46.6261818,25.1667879 44.7385051,24.4078384 43.2438788,22.8899394 C41.7492525,21.3720404 41.0012929,19.4326465 41,17.0717576 Z M43.6957576,17.0717576 C43.6957576,18.9141818 44.172202,20.3965253 45.1250909,21.5187879 C46.0779798,22.6410505 47.327596,23.2028283 48.8739394,23.2041212 C50.4254545,23.2041212 51.6802424,22.6423434 52.638303,21.5187879 C53.5963636,20.3952323 54.0786263,18.9128889 54.0850909,17.0717576 C54.0850909,15.2422626 53.6028283,13.7657374 52.638303,12.6421818 C51.6737778,11.5186263 50.4189899,10.9574949 48.8739394,10.9587879 C47.3224242,10.9587879 46.0728081,11.5205657 45.1250909,12.6441212 C44.1773737,13.7676768 43.7009293,15.2435556 43.6957576,17.0717576 Z"></path><path d="M70.0824261,23.582303 C69.3285884,24.0285568 68.5220417,24.3790594 67.6814564,24.625697 C66.9065592,24.8487063 66.1042899,24.9622904 65.2979413,24.9631515 C63.1180625,24.9631515 61.3564463,24.2397576 60.0130928,22.7929697 C58.6697392,21.3461818 57.9987089,19.4449293 58.0000019,17.0892121 C58.0000019,14.6882424 58.7175776,12.739798 60.1527291,11.2438788 C61.5878807,9.7479596 63.4626281,9 65.7769716,9 C66.5067857,9.0106757 67.2345208,9.08072506 67.9529716,9.20945455 C68.7804463,9.34650505 69.737214,9.55725253 70.8232746,9.84169697 L72.745214,9.06593939 L72.745214,22.4283636 C72.745214,24.213899 72.6605271,25.520404 72.4911534,26.3478788 C72.3424597,27.1215145 72.0497022,27.860316 71.6281231,28.5258182 C70.9908577,29.4891385 70.0844202,30.2438287 69.0215776,30.696 C67.7834618,31.2231176 66.4474127,31.48094 65.1020625,31.4523636 C64.1335045,31.4523045 63.1689244,31.3284732 62.2317594,31.0838788 C61.252533,30.8239772 60.3068642,30.4510466 59.41382,29.9726061 L58.9696988,26.7512727 L60.9575776,28.0506667 C61.5573127,28.4240193 62.2116549,28.7014604 62.8969716,28.8729697 C63.6457641,29.0836796 64.4192481,29.1938978 65.1970928,29.2007273 C66.7486079,29.2007273 67.9516786,28.8128485 68.8063049,28.0370909 C69.6609312,27.2613333 70.0863049,26.1571717 70.0824261,24.7246061 L70.0824261,23.582303 Z M70.0824261,21.5595152 L70.0824261,12.0739394 C69.4432737,11.7542576 68.7741844,11.4983147 68.0848503,11.3098182 C67.4816476,11.1457578 66.859767,11.0603633 66.2346685,11.0557576 C64.581012,11.0557576 63.2499413,11.6117172 62.2414564,12.7236364 C61.2329716,13.8355556 60.7280827,15.3146667 60.7267897,17.1609697 C60.7267897,18.9348687 61.179315,20.3428687 62.0843655,21.3849697 C62.989416,22.4270707 64.2086483,22.9474747 65.7420625,22.9461818 C66.3845516,22.9385817 67.0221469,22.8332967 67.6329716,22.6339394 C68.4792669,22.3480186 69.2988853,21.9885027 70.0824261,21.5595152 L70.0824261,21.5595152 Z"></path><path d="M75,9 L77.8276364,9 L82.2649697,20.6363636 L87.1483636,9 L89.4504242,9 L82.3813333,25.3238788 L82.2649697,25.5546667 C81.1478788,28.0965657 80.2874343,29.9066667 79.6836364,30.9849697 L76.7415758,30.9849697 C77.3683498,30.3346009 77.9302011,29.6246546 78.4191515,28.8652121 C79.0313917,27.8817808 79.5750659,26.8572886 80.046303,25.7990303 L81.0004848,23.7452121 L75,9 Z"></path></g></svg>
+      </header>
+      <main class="ErrorPage__main">
+        <div class="Alert Alert--danger">
+          <div class="Alert--danger__icon">
+            <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="none" d="M0 0h24v24H0V0z"/><path d="M11 15h2v2h-2zm0-8h2v6h-2zm.99-5C6.47 2 2 6.48 2 12s4.47 10 9.99 10C17.52 22 22 17.52 22 12S17.52 2 11.99 2zM12 20c-4.42 0-8-3.58-8-8s3.58-8 8-8 8 3.58 8 8-3.58 8-8 8z"/></svg>
+          </div>
+          <div class="Alert__content">
+            <p class="Alert__title">Not authorized.</p>
+            <%
+              # TODO: Parameterize the below message to be app specific, via NulogySSO engine config.
+            %>
+            <p class="Alert__message">You do not have permission to access Nulogy.</p>
+          </div>
+        </div>
+
+      </main>
+    </div>
+    <div class="ErrorPage__logout" >
+      <%= link_to("Logout", nulogy_sso.logout_path, class: "Link") %>
+    </div>
+  </div>
+  <footer class="ErrorPage__footer">
+    © 2007-<%= Date.today.year %> Nulogy Corporation
+  </footer>
+</div>
+</body>
+</html>

data/config/initializers/inflections.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Inflections are used so that "SSO" can be used in the NulogySSO module name
+# with this exact casing and still allow rails to evaluate directory paths as nulogy_sso
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym "SSO"
+end

data/config/routes.rb

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

data/lib/nulogy_sso/controller_helper.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module NulogySSO
+
+  # A mix-in that is intended to enhance a controller with NulogySSO authentication code.
+  # It is recommended to `include NulogySSO::ControllerHelper` in your ApplicationController.
+  module ControllerHelper
+    extend ActiveSupport::Concern
+
+    included do
+      # Makes the commonly used @current_user variable available to controllers and views.
+      # This emulates a code pattern popular in Rails apps using Devise.
+      attr_reader :current_user
+      helper_method :current_user
+    end
+
+    def authenticate_sso_user
+      raw_token = cookies[NulogySSO.auth_cookie_key]
+      return redirect_to nulogy_sso.login_path if raw_token.blank?
+
+      @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

@@ -0,0 +1,29 @@
+module NulogySSO
+  class Engine < ::Rails::Engine
+    isolate_namespace 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."
+      end
+
+      if NulogySSO.find_user_by_email.blank?
+        raise "Missing find_user_by_email config lambda."
+      end
+
+      if NulogySSO.validate_user.blank?
+        raise "Missing validate_user config lambda."
+      end
+    end
+  end
+end