README.md in nulogy_sso-1.0.0 vs README.md in nulogy_sso-2.0.0
- old
+ new
@@ -1,9 +1,12 @@
# NulogySSO
[](https://rubygems.org/gems/nulogy_sso "View this project in Rubygems")
+## Auth0
+For more information on Auth0 see the [Auth0 documentation](https://auth0.com/docs/flows/concepts/auth-code#how-it-works).
+
## 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:
@@ -26,12 +29,36 @@
# 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.
+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. An example configuration for local development would look like:
+```yaml
+default: &default
+ audience: <%= ENV.fetch("SSO_AUDIENCE", "auth.nulogy.net") %>
+ client_id: <%= ENV.fetch("SSO_CLIENT_ID", "SSO CLIENT ID FROM AUTH0") %>
+ client_secret: <%= ENV.fetch("SSO_CLIENT_SECRET", "SSO CLIENT SECRET FROM AUTH0") %>
+ base_uri: <%= ENV.fetch("SSO_BASE_URI", "") %>
+ cookie_prefix: <%= ENV.fetch("SSO_COOKIE_PREFIX", "") %>
+ login_uri: <%= ENV.fetch("SSO_LOGIN_URI", "") %>
+ redirect_uri: <%= ENV.fetch("SSO_REDIRECT_URI", "") %>
+
+development:
+ <<: *default
+ base_uri: <%= ENV.fetch("SSO_BASE_URI", "https://auth-dev.nulogy.net") %>
+ cookie_prefix: <%= ENV.fetch("SSO_COOKIE_PREFIX", "dev") %>
+ login_uri: <%= ENV.fetch("SSO_LOGIN_URI", "http://localhost:3000/sso/validate_authentication_code") %>
+ redirect_uri: <%= ENV.fetch("SSO_REDIRECT_URI", "http://localhost:3000") %>
+
+test:
+ <<: *default
+
+production:
+ <<: *default
+```
+
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.
@@ -41,10 +68,15 @@
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) { }
+NulogySSO.handle_sso_error = ->(controller: , error:) { }
+
+# Handle how unauthenticated requests should be responded to. The default is to redirect to the defined login page.
+# For API based applications this should be overriden to provide a meaningful error as per your API's contract (i.e. an HTTP 401 error code)
+# Additionally, this could be overriden if an application should bypass SSO when running tests.
+NulogySSO.handle_unauthenticated_request = ->(controller) { controller.redirect_to sso_engine.login_path }
```
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