READynamic

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

Your READynamic customers or users are likely to have accounts set up to log on to a variety of online services and social media sites, like Twitter and Facebook. It is possible to authorize a user to access multiple platforms by using a Single Sign-on (SSO) authentication service, using one of these social media sites as the source of the authentication records. For example, you have probably seen an offer to log on to a merchant site, like Etsy or Netflix, using your Facebook or Google account. This makes logging on to Etsy or Netflix faster, and you don’t have to keep track of an extra account name and password.

Within your institution, users and employees also work with a variety of different applications and online services, and many of them require their own password security. To make accessing these services and applications easier, you probably have a type of Single Sign-On service for your network, and with the same effect. In fact, you may use Google or Facebook as your Single Sign-On provider for your end users.

Or you may set up your own internal network provider server for this purpose. Every user or employee would be provided with a single network account and password, and when that user logs on to the network, he or she would be automatically authenticated to gain access to every system or service that person has been granted access to use. Using a Single Sign-On service is also helpful in that an administrator could use it to log user activities and to monitor user accounts.

You can add READynamic to your local Single Sign-On network environment, so that when a student or instructor logs on to your network, that user is also granted access to the READynamic platform. READynamic features a built-in OAuth2 client, and uses a remote authorization server to authenticate users who log on to the READynamic portal. OAuth2, or OmniAuth, is an open standard for authentication that is often used to allow users to log on to third party web sites with standard access accounts (such as accounts for Google or Facebook) without needing to provide a password.

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.