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:
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
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
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.
- Add a new custom module via the authentication tab.
- Give the provider a name: e.g.
RubyTestin the figure below.
Rubyunder module type.
- Under module locator, supply the name of the Ruby class in which you defined the authentication provider: e.g.
RubyTestAuthnModulein the figure below.
- Under module name, supply the value of the Name constant you defined at the top of your module file: e.g.
RubyTestAuthnin 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.