ScriptState

Introduction and overview

The ScriptState is used to compile and evaluate scripts written in Groovy. With access to the request and response objects and other nevisAuth beans, special user requirements can be scripted and, thus, this state serves as an alternative to a custom AuthState implementation. The following list shows the differences between a custom AuthState and a script in the ScriptState:

• Custom AuthState
  • Can be configured
  • Can be tested with the nevisAuth test harness
  • Can be debugged
• ScriptState
  • Rapid prototyping / rapid demonstrations
  • No complex project setup
  • Easy deployment
  • Can be tested with the nevisAuth test harness
  • No restart of nevisAuth necessary if script changes. (when configured so)

Scripts can either be embedded into the AuthState or through an external file. If the script is stored in another file, changes to it will be detected without restarting the nevisAuth instance (when configured so). The scripts are compiled into Java byte code and are recompiled only if an external script file is used and the file contents change.

New to ScriptState?

Start with Writing scripts in Groovy for practical patterns, a full working example, and testing guidance. For the complete API reference of all script variables, see Bound objects.

Description

The following table and chapters describe the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.scripting.ScriptState
Logging	Script
Auditing	none
Marker	none
Methods	process(all events)

Properties

• scriptLanguage (string, "groovy")

  The language used in the script. Only Groovy is supported.

• script (string, -)

  Either the script itself or the path to the script on the file system. If the script is located on the file system, the value of the script property must start with file://.

  caution

  While it is possible to specify a multi-line script as the value of this property, this is strongly discouraged. During parsing of the AuthState XML, any line breaks present in this property value will be collapsed to single spaces, which can distort the syntax and semantics of the script. We recommend referencing a script file on the file system instead.

• scriptTraceGroup (string, "Script")

  The trace group used for logging from the script.

• addAutoImports (boolean, true)

  Appends the following imports at the beginning of the script for convenience. Set it to false to turn this feature off.

  nevisAuth API:

  • HttpClients — special binding in the ScriptState; provides extra features on top of the regular HttpClients class. This is the only one that is a binding rather than an import.
  • HttpClient
  • Http

  java.time API:

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

• recompileOnChange (boolean, false)

  When set to true, nevisAuth watches the Groovy script file and triggers a reload and recompilation whenever the file contents change, without requiring a restart.

• parameter.[parameterName] (string, -)

  Properties prefixed with the string parameter are accessible from within the script via the parameters bean using the parameterName. For example: parameters.get("parameterName").

• parameter.httpclient.* (String)

  Configure the outgoing HTTP communication. For a list of valid HTTP properties, see HTTP Client.

Input

Depends on the script.

Transitions

Depends on the script.

Output

Depends on the script.

Errors

Depends on the script.

• lasterror=99

  lasterrorinfo=Script failed to compile

Notes

Depends on the script.

Example

For a complete working example with an AuthState XML configuration, a Groovy script, and matching JUnit tests, see the Full example: simple login script in the Groovy cookbook.

Testing

For a guide to testing your scripts, including a JUnit example and the full TestContext API, see Testing in the Groovy cookbook.