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.

To begin with, add the gem to your Gemfile:

gem "nulogy_sso"

Install the gem:

bundle

Routes can now be mounted into your application in routes.rb and served up at a specific URI prefix:

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

# 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 stored as a browser cookie. Add this code to the ApplicationController:

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

# 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 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. Please add an entry into 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)