Bound objects

Scripts running in the ScriptState can access context data from the current request. The following variables are bound to the script's execution context. For practical usage examples, see Writing scripts in Groovy.

Variable	Type	Purpose
request	AuthRequest	Read access to the incoming authentication request
inargs	java.util.Properties	Input arguments submitted by the user (read-only)
parameters	java.util.Map<String, String>	Unmodifiable map of parameter.* config properties
session	java.util.Map<String, String>	Lazy proxy over the user's session data
notes	java.util.Properties	Key-value store for passing data within a request
response	AuthResponse	Write access to the authentication response
outargs	java.util.Properties	Output arguments propagated back to nevisProxy
LOG	org.slf4j.Logger	SLF4J logger scoped to scriptTraceGroup
oocd	OutOfContextDataService	Persistent cross-request key-value storage
sessionCoordinator	SessionCoordinator	Low-level session lifecycle management
HttpClients	ScriptState binding	Creates or returns the cached HttpClient for this state

The addAutoImports property prepends a set of import statements for commonly needed classes (Http, HttpClient, and the java.time API). Those are not variable bindings — they are just imports, available as class references but not as pre-constructed objects.

The sections below cover the methods that are useful in practice. Additional methods exist on some of these objects but have no practical use in ScriptState scripts and are therefore omitted.

Inspecting variable values at runtime

To see the resolved values of all bound variables logged at INFO level, enable the Vars trace group in the logging configuration:

- name: Vars
  level: INFO

This is useful for a quick debugging pass to see exactly what inargs, session, notes, and other bindings contain during a real authentication flow.

request — AuthRequest

Provides read access to the incoming authentication request. Methods are grouped by category below.

Input

Signature	Description
String getInArg(String name)	Returns the value of the named input argument. Equivalent to inargs.getProperty(name). Input arguments include form fields, query parameters, and JSON body fields converted by nevisProxy — see inargs.
Properties getInArgs()	Returns all input arguments as a Properties map. This is the same object as the inargs binding.
String getHttpHeader(String headerFieldName)	Returns the value of an HTTP header forwarded by nevisProxy. Header name matching is case-insensitive per RFC-7230.
String getBasicAuthUserId()	Returns the user ID from the HTTP Basic Auth header, or null if not present.
String getBasicAuthPassword()	Returns the password from the HTTP Basic Auth header, or null if not present.

Request context

Signature	Description
String getMethod()	Returns the current authentication method name, e.g. authenticate or stepup. Use this to branch logic depending on the authentication phase.
String getResource()	Returns the original resource the user attempted to access before authentication was triggered by nevisProxy.
String getCurrentResource()	Returns the full URL of the current authentication request.
String getDomain()	Returns the Single-Sign-On domain name.
String getLanguage()	Returns the resolved language code for the end-user (e.g. en, de). Determined from the request, session, or browser headers in priority order.
String getClientType()	Returns the user agent string (HTTP User-Agent header).
String getContentType()	Returns the HTTP Content-Type of the incoming request.
Properties getLoginContext()	Returns all properties forwarded by nevisProxy. HTTP headers are included with the prefix connection.HttpHeader. (e.g. connection.HttpHeader.Referer). Prefer getHttpHeader(String) for accessing specific headers.
String[] getRequiredRoles()	Returns the roles requested by nevisProxy for this resource.
void setRequiredRoles(String[] roles)	Overrides the required roles for this request. nevisProxy evaluates these roles after the AuthState chain completes; if the session does not satisfy them, it may initiate step-up depending on the deployment configuration.

Session and authentication state

Signature	Description
NevisSession getSession(boolean createIt)	Returns the current session, optionally creating one if it does not exist. Prefer the session binding for simple attribute access. The returned NevisSession exposes invalidate() to terminate the session from within the script.
String getSessionAttribute(String name)	Returns a session attribute by name without going through the session binding. Returns null if there is no session or the attribute is not set. The corresponding setter is response.setSessionAttribute(String name, String value).
String getLoginId()	Returns the login ID accumulated so far in this authentication flow, or null.
String getUserId()	Returns the user ID accumulated so far in this authentication flow, or null.
String getAuthLevel()	Returns the authentication level accumulated so far, or null.

TLS and certificates

Signature	Description
String getClientCertAsString()	Returns the end-user's client certificate as a PEM-encoded string, or null if no client certificate is present.
X509Certificate getClientCert()	Returns the end-user's client certificate object, or null.
String getActorCertAsString()	Returns nevisProxy's actor certificate as a PEM-encoded string.

inargs — java.util.Properties

Input arguments submitted with the current request. Treat as read-only.

inargs contains not only HTML form fields but also other data that nevisProxy converts into input arguments, including:

• Form fields — values submitted via an HTML <form>.
• Query parameters — URL query string parameters forwarded by nevisProxy.
• JSON body fields — when nevisProxy is configured to parse a JSON request body and map its fields to inargs.

Signature	Description
String getProperty(String key)	Returns the value of the named input argument, or null.
boolean containsKey(Object key)	Returns true if the argument was present in the request.

Groovy shorthand: inargs['fieldName'] or inargs.fieldName.

---

parameters — java.util.Map<String, String>

An unmodifiable map containing all properties from the AuthState configuration that carry the parameter. prefix (prefix stripped). Attempting to write throws UnsupportedOperationException.

EL variable substitution (e.g. ${session:attr}, ${notes:key}) is performed on parameter values before the script runs, so parameters can reference runtime data.

Signature	Description
String get(String key)	Returns the value for the named configuration parameter.
boolean containsKey(Object key)	Returns true if the parameter is defined.

session — java.util.Map<String, String>

A lazy proxy over the user's session data. For a reference of standard ch.nevis.session.* attribute names, see Session attributes.

Read behaviour: Read operations on a non-existent session return data from an empty map — no session is created.

Write behaviour: The following operations automatically create the session if it does not yet exist: put, putAll, putIfAbsent, replace, computeIfAbsent, computeIfPresent, compute, merge.

Session values must be java.lang.String

Groovy's dynamic typing allows non-String values to be placed into the session map without a compile error. nevisAuth validates all session attributes after the script finishes and throws an AuthStateException if any attribute value is not a java.lang.String.

A common source of this error is Groovy's GString type. String interpolation with double quotes produces a GString, not a String:

session['key'] = "hello ${name}"   // GString — will fail validation
session['key'] = "hello ${name}".toString()  // String — safe
session['key'] = 'hello ' + name   // String concatenation — safe

Single-quoted strings ('...') are always java.lang.String. Call .toString() explicitly when using interpolation. Use JSON serialization to store complex data structures.

Groovy shorthand syntax works for all standard Map operations:

session['myKey'] = 'myValue'              // equivalent to session.put('myKey', 'myValue')
def existingValue = session['myKey']      // equivalent to session.get('myKey')
def defaultedValue = session.get('k', 'default')  // returns 'default' if key is absent

NevisSession — direct session object

request.getSession(boolean createIt) returns a NevisSession, which provides lower-level access to the session lifecycle beyond simple attribute reads and writes.

Signature	Description
String getId()	Returns the unique session ID.
Instant getCreationTime()	Returns the time when the session was created.
Instant getLastAccessedTime()	Returns the time when the session was last accessed.
boolean isNew()	Returns true if the current request is the first request for this session.
boolean isInvalid()	Returns true if the session has been invalidated.
boolean isTimedOut()	Returns true if the session has hit an inactivity or absolute timeout.
Map<String, String> getData()	Returns all session attributes as a mutable map.
String getAttribute(String name)	Returns the value of the named attribute, or null.
void setAttribute(String name, String value)	Sets a session attribute.
void removeAttribute(String name)	Removes a session attribute. Does nothing if the attribute is not present.
Iterator<String> getAttributeNamesIterator()	Returns an iterator over all attribute names.
void invalidate()	Destroys the session. After calling this, the session object must not be used again.

getData(), getAttribute(), getAttributeNamesIterator(), and setAttribute() throw IllegalStateException if called on an already-invalidated session.

notes — java.util.Properties

A key-value store used to pass data between AuthState instances within a single request. Notes are not persisted to the session.

Signature	Description
String getProperty(String key)	Returns the value for the given key, or null.
Object setProperty(String key, String value)	Sets a value.
boolean containsKey(Object key)	Returns true if the key exists.

Groovy shorthand: notes['key'] and notes['key'] = 'value' work as alternatives to getProperty/setProperty.

See Notes in the Groovy cookbook for usage patterns.

response — AuthResponse

Provides write access to the authentication response. Used to set the transition, identity information, GUI fields, and direct HTTP responses. Methods are grouped by category below.

Flow control

Signature	Description
void setResult(String result)	Sets the transition name after the script finishes. Must match a ResultCond name in the AuthState configuration.
String getResult()	Returns the currently set result.
void setError(int errno, String detail)	Sets an error code and human-readable message. Exposed in the GUI via ${notes:lasterror} and ${notes:lasterrorinfo}.
int getError()	Returns the current error code.
String getErrorDetail()	Returns the current error detail message.

Identity and authentication

Signature	Description
void setUserId(String userid)	Sets the authenticated user's internal identity.
void setLoginId(String loginid)	Sets the login ID as entered by the user (e.g. username).
void setAuthLevel(String authlevel)	Sets the authentication level, e.g. auth.weak or auth.strong.
void addActualRole(String role)	Adds a security role to the current authentication.
void removeActualRole(String role)	Removes a security role from the current authentication.
void setActualRoles(String[] roles)	Replaces all current roles with the provided array.
String[] getActualRoles()	Returns the currently set security roles.

GUI building

Signature	Description
void setGuiName(String name)	Sets the name of the GUI template to render. In some patterns this name is the trigger for including a corresponding JavaScript file.
void setGuiLabel(String label)	Sets the title label of the GUI.
String getGuiName()	Returns the currently set GUI name.
void addTextGuiField(String name, String label, String value)	Adds a text input field to the GUI.
void addPasswordGuiField(String name, String label, String value)	Adds a password input field to the GUI.
void addHiddenGuiField(String name, String label, String value)	Adds a hidden field to the GUI (not visible to the user).
void addButtonGuiField(String name, String label, String value)	Adds a submit button to the GUI.
void addButtonGuiField(String name, String label, String value, String cssClass, String icon, String iconCssClass)	Adds a button with custom CSS class and icon styling.
void addErrorGuiField(String name, String label, String value)	Adds an error display field to the GUI.
void addInfoGuiField(String name, String label, String value)	Adds an informational display field to the GUI.
void addRadioGuiField(String name, String label, String value)	Adds a radio button field to the GUI.
void addCheckBoxGuiField(String name, String label, String value)	Adds a checkbox field to the GUI.

Session

Signature	Description
void setSessionAttribute(String name, String value)	Creates a session if none exists, then sets the named string attribute. Equivalent to session.put(name, value).

Notes

Signature	Description
Properties getNotes()	Returns the notes Properties object. This is the same object as the notes binding.
String getNote(String name)	Returns the value of a named note as a String, or null.
void setNote(String name, Object value)	Sets a note.
void removeNote(String name)	Removes a note by name.

Output arguments

Signature	Description
Properties getOutArgs()	Returns the outargs Properties object. This is the same object as the outargs binding.
void addOutArg(String name, String value)	Adds a single output argument.
void removeOutArg(String name)	Removes an output argument.
String getOutArg(String name)	Returns the value of an output argument.

Direct HTTP response

Signature	Description
void setIsDirectResponse(boolean isDirect)	When true, instructs nevisProxy to send the response content and content type directly to the user agent without further processing.
void setContent(String responseContent)	Sets the response body. Use together with setIsDirectResponse(true).
void setContentType(String contentType)	Sets the Content-Type header.
void setHttpStatusCode(int status)	Sets the HTTP status code.
void setHeader(String name, String value)	Instructs nevisProxy to add the specified HTTP header to the response sent to the user agent.
String getHeader(String name)	Returns a previously set HTTP response header value.
void setCookie(String name, String value, String path, String domain, Duration maxAge, boolean secure, boolean httpOnly)	Instructs nevisProxy to set a cookie on the user agent.
void removeCookie(String name)	Instructs nevisProxy to expire a cookie by setting its value to "0" with no Max-Age, Path, or Domain attributes.

Redirect and transfer

Signature	Description
void setRedirect(String url, boolean restart)	Redirects the authentication flow to a different authentication entry point (a different login URL). Set restart to true to invalidate the current session first. Not intended for redirecting users to application URLs from scripts — use the nevis.transfer.* outargs for that (see Outargs and transfer).
void setTransferDestination(String url)	Sets the target URL for a transfer operation (redirect or form POST).
void setIsRedirectTransfer(boolean isRedirect)	If true, transfers the user agent via HTTP redirect. If false, submits a self-posting form to the target URL.
void addTransferField(String name, String value)	Adds a field to the form POST transfer. Only used when setIsRedirectTransfer(false) is set.
String getSignedTokenAsString()	Returns the signed authentication token as a string. Only available during the finish lifecycle phase after successful authentication.

outargs — java.util.Properties

Output arguments propagated back to nevisProxy with every response. Used for token handoff, redirect control, and transfer operations. Same API as notes above. Also accessible via response.getOutArgs() and response.addOutArg(name, value).

LOG — org.slf4j.Logger

The SLF4J logger bound to the trace group configured by scriptTraceGroup (default: Script). Supports parameterised log messages with {} placeholders, which avoids string concatenation overhead.

Signature	Description
void debug(String format, Object... args)	Logs a debug-level message.
void info(String format, Object... args)	Logs an info-level message.
void warn(String format, Object... args)	Logs a warn-level message.
void error(String format, Object... args)	Logs an error-level message.
void error(String message, Throwable t)	Logs an error-level message with an exception stack trace.

oocd — OutOfContextDataService

Provides persistent, cross-request key-value storage backed by the configured out-of-context data store. Values carry an explicit expiration time. For background and configuration, see Shared out-of-context data.

Signature	Description
String get(String key)	Returns the stored value for the given key, or null if not present or expired.
Map<String, String> getWithPrefix(String keyPrefix)	Returns all entries whose key starts with the given prefix.
void set(String key, String value, Instant notOnOrAfter)	Stores a key-value pair that expires at the given Instant.
void set(Map<String, String> keyValuePairs, Instant notOnOrAfter)	Stores multiple key-value pairs with a shared expiration time.
void remove(String key)	Removes the entry for the given key.
void removeWithPrefix(String keyPrefix)	Removes all entries whose key starts with the given prefix.

See Out-of-context data in the Groovy cookbook for usage examples.

sessionCoordinator — SessionCoordinator

Low-level session management service. Use this binding only when direct session lifecycle control is required; prefer the session binding or request.getSession(boolean) for typical session attribute access.

These methods were originally designed to be called by nevisProxy. The actor parameter identifies the calling nevisProxy instance; pass null from a ScriptState script.

Signature	Description
Session getSession(String sessionId, boolean createIt)	Returns the session with the given ID, optionally creating it.
Properties getProperties(String actor, String sessionId, List<String> filters)	Returns a filtered subset of session properties. Internally acquires and releases the write lock — do not call this while you hold the lock on the same session.
void setProperties(String actor, String sessionId, Properties props)	Merges the supplied properties into the session — existing attributes not in props are preserved, supplied keys are added or overwritten. Convenient alternative to calling getSession() + setAttribute + release() when you only need to write and do not need to read or inspect the session. Internally acquires and releases the write lock — do not call this while you hold the lock on the same session. Throws SessionException if the session does not exist.
boolean killSession(String actor, String sessionId)	Terminates the session with the given ID. Returns true if successful. Internally acquires the write lock — do not call this while holding the lock on the same session (see danger note below).
void killSessions(String actor, String attributeName, String attributeValue)	Terminates all sessions that have the given attribute set to the given value. Internally calls killSession for each match, which acquires the write lock — same locking constraints apply as for killSession.
String[] getSessionList(String attributeName, String attributeValue)	Returns the IDs of all sessions that have the given attribute set to the given value.

Risk of deadlock and IllegalMonitorStateException

Every method except getSessionList acquires a write lock on the target session. Misuse can cause deadlocks that halt nevisAuth.

Never pass the current session's ID to these methods. The engine already holds the write lock on the current session for the duration of script execution. Attempting to lock it again from the same thread throws IllegalMonitorStateException immediately (it does not block). Locking it from a different thread can cause a deadlock.

To terminate another session, choose one of these two approaches:

Kill by ID — when you don't need to inspect the session first:

sessionCoordinator.killSession(null, otherSessionId)

Get session and invalidate — when you need to inspect the session before terminating it. invalidate() both destroys the session and releases the lock:

def otherSession = sessionCoordinator.getSession(otherSessionId, false)
if (otherSession != null) {
    try {
        // ... inspect session ...
    } finally {
        otherSession.invalidate()
    }
}

Do not call killSession while holding the lock from getSession on the same session — killSession internally re-acquires the write lock.

To read or modify the current session, use the session binding or request.getSession(boolean) instead.

To terminate the current session from within a script:

def currentSession = request.getSession(false)
if (currentSession != null) {
    currentSession.invalidate()
}

invalidate() destroys the session and releases the write lock — after which the session object must not be used again. getSession(false) returns null if no session exists, hence the null check.

Session — the session object returned by sessionCoordinator

sessionCoordinator.getSession() returns a Session, which extends NevisSession (see above) and adds the following methods:

Signature	Description
String get(String name)	Returns a session attribute by name, or null if not set.
String getLanguage()	Returns the user's language as stored in the session, or null.
String getLoginResource()	Returns the resource that triggered authentication for this session.
String[] getSecurityRoles()	Returns the authenticated user's current security roles as stored in the session.
Instant getNotAfter()	Returns the absolute expiration date of this session.
void setNotAfter(Instant instant)	Sets the absolute expiration date of this session. The session will expire at this instant at the latest.
void set(String name, String value, boolean preserve)	Sets a custom session attribute. If preserve is true, an existing value is not overwritten.
void release()	Releases the lock held on this session. Must be called after every sessionCoordinator.getSession() call once you are done with the session, or the session remains locked and other requests will block.

Always release sessions obtained via sessionCoordinator.getSession()

Every call to sessionCoordinator.getSession() returns a write-locked Session. If you do not release it, the lock is never freed and subsequent requests for that session will be blocked forever, filling up worker threads and rendering nevisAuth inaccessible. Always call release() in a finally block:

def otherSession = sessionCoordinator.getSession(otherSessionId, false)
if (otherSession != null) {
    try {
        def userId = otherSession.get('ch.nevis.session.userid')
        // ...
    } finally {
        otherSession.release()
    }
}

HttpClients — ScriptState binding

HttpClients is not an auto-import; it is a special binding available only within ScriptState scripts. It extends the standard HttpClients class with one additional method:

Signature	Description
HttpClient create()	Creates or returns the cached HttpClient for this ScriptState instance, configured automatically from parameter.httpclient.* properties. The same client instance is reused across all requests to this ScriptState (connection pooling).

See HTTP client in the Groovy cookbook for the full lifecycle discussion and examples.