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.apache.commons.collections4.Bag;
Bag<String> bag = new HashBag<>();

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);
}

caution

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');

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');

Date handling

Groovy ScriptStates rely on the java.time API to parse and do operation on dates. An overview of the java.time API is available in the official documenation.

The following types are auto imported in the groovy scripts:

• DateTimeFormatter
• Instant
• LocalDate
• LocalDateTime
• OffsetDateTime
• ZonedDateTime
• ZoneOffset
• ZoneId
• ChronoUnit
• Duration

Standard date formats handled by Java can be found in the official documentation, including formatting.

Visit Appendix J for detailed examples.