Quickstart

The nevisAuth SDK is the starting point for the development of custom authentication plugins. It is part of every nevisAuth installation and is located at:

/opt/nevisauth/resources/nevisauth-sdk-<nevisAuth-version>.tar.gz

The SDK archive contains all resources required to develop authentication plugins for nevisAuth. A Maven archetype is provided to enable fast bootstrapping of nevisAuth authentication plugin projects. The archetype assists you with the creation of a Maven POM file that already contains the required dependencies to the nevisAuth API and commons library.

The structure of the nevisAuth SDK is as follows:

• archetypes

  This folder contains a Maven archetype for authentication plugin projects.

• docs

  This folder contains documentation for developers.

• libs

  This folder contains the official API libraries and the corresponding Javadocs. The nevisauth-test-authstateharness-fat JAR is also located here.

• scripts

  This folder contains scripts to set up the SDK.

• resources

  This folder contains files that are required for the integration of the example authentication plugin.

The fastest way to get started with your own nevisAuth authentication plugin is to generate a new Maven project based on the archetype.

Creating your first Authentication Plugin

As the first step install the provided Java libraries and the Maven archetype in the Maven repository of the development workstation. If you are working in a Unix/Linux environment, you can automate this by executing the provided script:

./scripts/add-dependencies-to-maven-repo.sh

Otherwise, you can manually install the necessary Maven dependencies by executing the following commands:

mvn install:install-file -Dfile=./libs/nevisauth-authstate-api-<nevisAuth-version>.jar -DgroupId=ch.nevis.nevisauth -DartifactId=nevisauth-authstate-api -Dversion=<nevisAuth-version> -Dpackaging=jar
mvn install:install-file -Dfile=./libs/nevisauth-commons-<nevisAuth-version>.jar -DgroupId=ch.nevis.nevisauth -DartifactId=nevisauth-commons -Dversion=<nevisAuth-version> -Dpackaging=jar
cd archetypes\AuthPlugin
mvn clean install

This will install the required nevisAuth API libraries and the Maven archetype in your local Maven respository.

Creating a Maven Project

To create a new authentication plugin project, change to the directory where you would like your project to be located:

cd ~/projects

Then execute:

mvn archetype:generate \
-DarchetypeCatalog=local \
-DarchetypeGroupId=ch.nevis.nevisauth \
-DarchetypeArtifactId=auth-plugin-archetype \
-DarchetypeVersion=<nevisAuth-version> \
-DgroupId=ch.example \
-DartifactId=auth-state-example \
-DinteractiveMode=false

As a result, a project with the name auth-state-example is created. The resulting Maven project can be imported to various IDEs, e.g., Eclipse and IntelliJ.

Projects created from the archetype already contain an example AuthState. The example AuthState implements authentication by checking the incoming user name and password against a user name/password hash list in a file.

info

When implementing your own custom plugin, it is recommended to create the project based on the archetype. After creation, you can replace the example AuthState by your own implementation.

Packaging and Deploying the Plugin

The authentication plugin can be built with the following Maven command:

cd auth-state-example
mvn clean package

To use the AuthState contained in the authentication plugin, extract the resulting ZIP archive from the target directory of the auth-state-example directory to the plugin directory of a nevisAuth instance.

For example, if your nevisAuth instance is named default and runs on the same machine, you can extract it by executing the following command (You may need root access to extract it to this directory):

unzip target/auth-state-example-1.0-SNAPSHOT.zip -d /var/opt/nevisauth/default/plugin/

To configure nevisAuth to use the AuthState, open the configuration by typing

nevisauth config

In the XML config, add the following AuthState elements below the Domain element:

<AuthState name="UseridPasswordState" class="ch.example.UseridPasswordFileAuthState"
        classPath="/var/opt/nevisauth/default/plugin/auth-state-example-1.0-SNAPSHOT"
        classLoadStrategy="PARENT_LAST">
    <ResultCond name="ok" next="AuthDone"/>
    <ResultCond name="failed" next="AuthError" />
    <Response value="AUTH_CONTINUE">
      <Gui name="AuthUidPwDialog" label="login.test.label">
        <GuiElem name="lasterror"    type="error"   label="${notes:lasterrorinfo}" value="${notes:lasterror}"/>
        <GuiElem name="info"         type="info"    label="login.test.text"/>
        <GuiElem name="username" type="text"    label="userid.label" value="${notes:loginid}"/>
        <GuiElem name="password" type="pw-text" label="password.label"/>
        <GuiElem name="submit" type="button"        label="submit.button.label" value="Login"/>
      </Gui>
    </Response>
    <property name="passwordFileLocation" value="/var/opt/nevisauth/default/conf/passwords.txt"/>
</AuthState>

<AuthState name="AuthDone" class="ch.nevis.esauth.auth.states.standard.AuthDone">
  <Response value="AUTH_DONE">
    <Gui name="AuthDoneDialog"/>
  </Response>
</AuthState>

<AuthState name="AuthError" class="ch.nevis.esauth.auth.states.standard.AuthError">
    <Response value="AUTH_ERROR">
        <Gui name="AuthErrorDialog"/>
    </Response>
</AuthState>

Make sure the UseridPasswordState is referenced by a Domain element, e.g.,

<Domain name="SSO_TEST" default="true"
        reauthInterval="0"
        inactiveInterval="1800">
  <Entry method="authenticate" state="UseridPasswordState"/>
</Domain>

Copy the user credential file from the resources directory into the nevisAuth configuration directory:

cp resources/passwords.txt /var/opt/nevisauth/default/conf/passwords.txt

The file contains the following credentials for testing the setup:

Username	Password
testuser1	password1
testuser2	password2
testuser3	password3

Now, you are ready to restart nevisAuth to read the new configuration:

nevisauth restart

That's it. You have successfully deployed an AuthState of the type UseridPasswordFileAuthState and can try to log in, using the credentials defined in the password file.