# 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)