# NulogySSO

[![Gem](https://img.shields.io/gem/v/nulogy_sso?label=nulogy_sso)](https://rubygems.org/gems/nulogy_sso "View this project in Rubygems")

## 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 the below code into `config/initializers/nulogy_sso.rb`, with the appropriate modifications implemented. For `sso_config`, refer to [nulogy_sso.rb](lib/nulogy_sso.rb) for a list of required keys and [sso_config.yml](spec/dummy/config/sso_config.yml) for an example config file.

```ruby
# 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.sso_config = Rails::Application.config_for(:sso)

# Return the user matching the provided email, or nil if not found.
NulogySSO.find_user_by_email = ->(email) { nil } 

# 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 NulogySSO 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 including `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 `NulogySSO::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 NulogySSO 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)
* Add additional hooks, as necessitated by unique use cases for new apps using this engine