Writing scripts in Groovy

Scripts can be written in any JSR-223 supported language. The following subchapters give examples of how certain tasks can be completed with Groovy.Importing Libraries and Scripts in Groovy.

To be able to use a library from inside a Groovy script, one should place the libraries JAR inside the lib folder of the nevisAuth instance. The libraries classes can now be made accessible by using Java import statements inside the script.

import org.joda.time.DateTime;
DateTime test = new DateTime();

To include another script, you may add the following line to the script linked to your ScriptState:

evaluate(new File("/var/opt/nevisauth/<instance name>/conf/OtherScript.gy"))

Be advised that the name of the script you want to link needs to conform to Java's class naming rules.

For a complete Groovy example, have a look at /opt/nevisauth/examples/scripting.

Logging

Logging can be done using a trace group. Either use the default trace group "Script" or define your own. For this, use the ScriptState, which enables you to do separate logging and log levels per script.

To be able to set the trace group per ScriptState/script, the ScriptState configuration property scriptTraceGroup is needed. For example:

<property name="scriptTraceGroup" value="SimpleScript"/>

The following example of a log statement in the script writes "Hello World" to the log file:

 LOG.debug('Hello World');

Information logged using LOG will only be visible if the log level in nevisauth config log is set to the log level you want to use. For example, make sure that the following line exists and change the value to the desired log level:

<category name="SimpleScript"> <priority value="DEBUG"/> </category>

The name must be as set in the ScriptState's configuration under property scriptTraceGroup (or Script for the default trace group).

Accessing and setting properties and the result

To set the property exampleProperty in the notes to the URL of the request, do:

String url = request.getCurrentResource();
notes.setProperty('exampleProperty', url);

You may check the current authentication level of the session as follows:

String sessionAuthLevel = session.get('ch.nevis.session.authlevel');
LOG.info('session authlevel: ' + sessionAuthLevel);

if (sessionAuthLevel == 'auth.weak') {
 LOG.info('Current session auth level: ' + sessionAuthLevel);
}

Be aware that no session is automatically created by the ScriptState. That is, if there was no session established before the script starts being processed, there also won't be a session established after the script has been processed, except explicitly done in the script.

If you would like to ensure that a session is present and may be accessed, use:

if (request.getSession(false) == null) {
 session = request.getSession(true).getData();
}
session[key] = "value";

You can set the result condition by:

 response.setResult('myResultConditionName');

In case of an error, the code and error message can be changed as follows:

response.setError(AUTH_FAILED, 'My error description');

If you use the AUTH_FAILED constant, make sure you import it at the beginning of the script with:

import static ch.nevis.esauth.auth.engine.AuthConst.AUTH_FAILED;

Scripts with parameters

It may be useful to give parameters from the configuration to a script. This can be done by defining configuration properties in the AuthState configuration.

For example, parameters specified in the AuthState configuration as

<property name="parameter.exampleParameter" value="exampleParameterValue"/>

can be accessed from within the script by:

 parameters.get('exampleParameter');

Installing a specific Groovy version

To use another Groovy version than the one delivered with nevisAuth, place the desired version of the Groovy-all JAR into var/opt/nevisauth/<instance>/lib. This overrides the default version shipped in /opt/nevisauth/<version>/plugin/thirdparty/jsr233.

Troubleshooting

If providing a specific Groovy version does not seem to have any effect, make sure that the env.conf configuration file contains an entry like the one in the next code block:

CLASSPATH="/var/opt/nevisauth/<instance>/lib/*:"