READynamic

Editing the Server Configuration Files for Single Sign-On (SSO) using OAuth2

To enable your READynamic environment to work with OAuth2, you need to update the settings in two configuration files provided with your software installation package:

  • server_configuration_overrides.yml
  • omniauth_overrides.yml

Enable the OmniAuth Single Sign-On using the server_configuration_overrides.yml file, and then set the parameters for the service in omniauth_overrides.yml.

Normally Datalogics engineers will edit these two YML configuration files on your behalf when you set up READynamic on your local servers. So you probably won’t need to work with them. But we describe here the parameters for the configuration files in case you want to change some of these settings, or create your own strategy.

Also, if you don’t enable OmniAuth in the server_configurations_overrides.yml file, you don’t need the omniauth_overrides.yml file.

server_configurations_overrides.yml

Start with the server_configuration_overrides.yml file. Look for the settings under Defaults, omniauth, and login_strategy.

These are default values for an environment that is not using OAuth2:

login_strategy:
   enabled: false
   redirect: /auth/

The OmniAuth service is enabled for your local READynamic environment by setting the login_strategy to “true.”

Then, enter the path to redirect the user’s portal home page to when the user logs on to READynamic. This will be “auth” followed by the OAuth2 strategy name.
The parameters in the configuration file might look something like this:

login_strategy:
   enabled: true
   redirect: /auth/boxcollege_oauth

Note “boxcollege_oauth.” This is the name of the READynamic strategy, while “/auth/” refers to a folder in your READynamic installation package where the strategy is found. The strategy is in the form of a Ruby file (.rb). When authenticating, the Single Sign-On provider (such as Google) refers to the OAuth2 strategy to find the authentication records for the user seeking to log on.

Throughout this documentation we use the example of a READynamic customer known as “Box College,” so this example uses “boxcollege_oauth” as the strategy name.

omniauth_configurations.yml

Edit the parameter settings in omniauth_overrides.yml to define your Single Sign-On environment.

As noted earlier, Datalogics will provide you with a strategy and a completed set of configuration files. But you are free to create and name your own OAuth2 strategy, and to edit the configuration files to set up your READynamic environment to work with your strategy.

First, your configuration file must have a key with the OAuth2 strategy name. This strategy is named in the server_configuration_overrides.yml file. In our example, we use the strategy name “boxcollege_oauth”:

Omni_auth_overrides.yml sample file, strategy name

Find the strategy parameter values in omniauth_overrides.yml. By default this set of parameters would look something like this:

<strategy_name>:
    app_id: app_id
    secret: secret
    authorize_url: http://example.com/Login
    callback_url: http://localhost:3000/auth/ucsyd/callback

Enter the name of the strategy to serve as a key in the omniauth_overrides.yml file. In our example you would use a key called “boxcollege_oauth.” Your edited parameters might look something like this.

Omniauth_overrides.yml file, settings

Under this key four parameters appear.

app_id The application ID that is used with the customer’s OAuth2 service provider. This identifies the software product or service in use. Here we identify the app by using the name of the product, “readynamic.” The application ID is assigned by the service provider.
secret A security key used to identify the OAuth2 consumer with the customer’s service provider. The Single Sign-On service provider will provide this code.
authorize_url The web address of the OAuth2 service provider where your client web browser will be redirected. The service provider will also set up this address. If the OAuth2 service provider your institution uses is Google, then “google.com” would appear as part of this web address. But it is also possible that your institution provides an internal OAuth2 service provider, on a local server. In that case the authorize_url will refer to a custom address for a local server.
callback_url The customer web address, hosted on your local server. After the OAuth2 service provider authorizes the client for access, the client will be sent back to this address to access READynamic. For READynamic, this is usually the URL for your customer library portal screen. In our example, “http://boxcollege.readynamic.com” serves as the sample web address.

Summary

Change the settings for the parameters In the server_configuration_overrides.yml file to turn on the OAuth2 Single Sign-On service, and to redirect to your OAuth2 strategy key, in our example “/auth/boxcollege_oauth.”

Change the settings for the parameters in the omniauth_overrides.yml file to provide:

  • the code that identifies the READynamic application
  • the security key needed to authenticate each user
  • the web address of the service provider for the user to gain access
  • the web address to redirect the user after that user account has been authorized to log on to READynamic

When one of your users visits the READynamic user portal, the READynamic server immediately redirects that user to the service provider’s web address, the authorize_url. The READymamic server passes an API request to the OAuth2 service provider containing the app_id, secret, and callback_url.

The app_id and secret identify the system being accessed (READynamic) and demonstrate that this system is authorized to request that individual users be validated for access. The user is presented with a page that asks for the user’s login credentials. After the user enters those credentials, the browser is then redirected to the web address for the READynamic user portal, the callback_url. From the READynamic library screen the user will be able to open and read eBooks.