OpenAthens LA support ended on 31 March 2020


Skip to end of metadata
Go to start of metadata

Custom authentication modules are used to provide authentication against authentication systems where there is not a built-in authentication provider. The authentication still takes place within the OpenAthens Atacama platform instead of delegating the entire process as you might with Kerberos. This has the advantage of using the same login templates that the built-in providers use which means no change to the login screens that users see.

Custom authentication modules may be written as Ruby modules (recommended) or native modules (which usually involves C/C++ code and is not recommended).

There are four steps involved in writing a custom authentication module using Ruby:

Writing an authentication provider

An authentication provider is what is referred to as an Atacama action. This action will be called by the Atacama platform whenever an authentication attempt is made by a user. This action is defined within an Atacama module. Modules may provide several actions, but typically authentication modules will provide a single one.

Actions are written as Ruby classes extending the Atacama::Action class. The mod_openathens distribution provides an example Ruby authentication module which provides a class called OALAAuthenticator that extends Atacama::Action. This should be used as a base class for writing an authentication module.

Modules define additional properties about themselves such as name, version etc. These are used to tell the OpenAthens platform how to load and use the module.

The following code is an example of an authentication module:

class RubyTestAuthnModule < Atacama::Module
   Name = "RubyTestAuthn"
   Version = "1.0.0"
   Dependencies = nil
   Constants = nil
   DataSources = {}

   class AuthnAction < OALAAuthenticator
     def authenticate(username, password)
        if !(username.eql? "username" and password.eql? "password")
           raise"Invalid username/password", "BadAuth")

   Actions = { "authenticate" => AuthnAction }

The above code is not complete. Working example code is supplied with the software. If you are using a prebuilt virtual machine, you can find it at /usr/share/openathens-la/ruby/authn.rb

Firstly, we define the module name: RubyTestAuthn and version: 1.0.0. We may also define module dependencies, constants or data sources but these will typically be left blank.

Next, we define our authentication class AuthnAction extending OALAAuthenticator. This simply defines a single method called authenticate that receives a username and password. It is the job of this method to authenticate the user, as required, and raise an exception if this fails.

Finally, we define a list of Actions that this module provides. This is simply a way of mapping the name by which the OpenAthens platform refers to the action (authenticate) with the class name implementing this action (AuthnAction). OpenAthens LA requires that this action must be called authenticate, so you should not change this from the example shown above.

Installing the Authentication Provider

Once written, the module must be installed under the /modules directory under the location where the Atacama platform has been installed. This will usually be /usr/share/atacama-platform/modules. The file containing the module class must end in .rb.

Configuring the Authentication Provider

Once the module has been written and installed it must be defined as a custom authentication provider in the Administration Console.

  1. Add a new custom module via the authentication tab.
  2. Give the provider a name: e.g. RubyTest in the figure below.
  3. Choose Ruby under module type.
  4. Under module locator, supply the name of the Ruby class in which you defined the authentication provider: e.g. RubyTestAuthnModule in the figure below.
  5. Under module name, supply the value of the Name constant you defined at the top of your module file: e.g. RubyTestAuthn in the figure below.

Configuring the runtime to use the Authentication Provider

This is done when adding a runtime connection or editing an existing runtime connection on the overview tab. At step 4 of the configuration wizard, you can select the relevant authentication provider:

You will need to publish the configuration so that the configuration details are passed to the Runtime.

  • No labels