Variable expressions
Variable expressions access and possibly filter values of the request context at runtime. The syntax is as follows:
<Element attribute="Some ${source:name:filter:pattern} text" />
The separator between source and name can be any non-alphanumeric character except }
, but for good readability of the configuration, :
should be used where possible.
The attributes source and name are required; filter and pattern are optional. filter and pattern may not be used with the separator .
.
Variable expression evaluation can be recursive.
Variable sources
Variables can be retrieved from the following sources:
inargs
Any user input (URL query or form post data).
Example:
${inargs:isiwebuserid}
inctx
Any client context (execution context, sent by the caller, e.g., client IP).
Example:
${inctx:connection.ClientIP}
sess
(orsession
)Any previously stored authentication session data.
Example:
${sess:my.session.variable}
notes
Any temporary data, set by previous AuthState processing on the same request.
Example:
${notes:lasterror}
outargs
Any authentication processing output, set by the AuthState(s).
Example:
${outargs:my.token}
request
All request attributes available during authentication processing.
Example:
${request:userId}
response
All response attributes available during authentication processing.
Example:
${response:error}
litdict
All attributes, stored in the literal dictionary files .
cookie
Special pseudo-scope for accessing cookies sent by the client.
header
Special pseudo-scope for accessing HTTP headers of the client connection. The header name resolving is case insensitive (RFC2616).
Example:
${header:host}
system
Pseudo-variables providing access to special system functions.
property
All system properties, as available within the Java runtime environment.
${property:line.separator}
will return the systems line separator characters;${property:file.separator}
will emit the systems file separation character.oocd
Special pseudo-code for read-only access to OutOfContextDataService entries.
For a detailed list of available attributes, see Scopes and predefined variables. Variable values which evaluate to arrays will be transformed into a comma-separated list.
Filter expressions
A filter may be defined in the form of a regular expression (as defined in http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html/). Depending on the result of the matching, the output will be:
- An empty string, if the value did not match the regular expression.
- The whole matching substring of the value, if the regular expression matches but does not define any groupings.
- The value of the grouping, if the regular expression matches and defines a grouping.
If a filter is defined, an additional pattern can also be specified. The pattern may use references to filter groupings using the common $0
,$1
syntax.
Regular expressions that contain curly brackets, like ^.*{0}$
, need to be escaped with a backslash: ^.*\{0\}$
.
"Mary had a ${inargs:my.test.attribute} lamb" -> "Mary had a little.fluffy lamb"
"Mary had a ${inargs/my.test.attribute/^.*$} lamb" -> "Mary had a little.fluffy lamb"
"Mary had a ${inargs|my.test.attribute|^\W+$} lamb" -> "Mary had a lamb"
"Mary had a ${inargs|my.test.attribute|^(\w+).*$} lamb" -> "Mary had a little lamb"
"Mary had a ${inargs my.test.attribute ^\w+\.(\w+)$} lamb" -> "Mary had a fluffy lamb"
"Mary had a ${inargs|my.test.attribute|^(\w+)\.(\w+)$|really $2 and $1} lamb" -> "Mary had a really fluffy and little lamb"
"Mary had a ${inargs|my.test.attribute|^.*$|really cute} lamb" -> "Mary had a really cute lamb"
"Mary had a ${inargs|my.test.attribute|^.*\{0\}$} lamb" -> "Mary had a lamb"
"Mary had a ${inargs|my.test.attribute|^.*\{8\}$} lamb" -> "Mary had a little.fluffy lamb"
Scopes and predefined variables
Source | Name | Description |
---|---|---|
request | actor (read-only) | The identification of the actor (client) communicating with nevisAuth on behalf of the user. |
authLevel | The authentication level obtained by the user. | |
clientCertAsString (read-only) | The certificate of the client, if available. | |
actorCertAsString | The certificate of the actor, extracted from the SSL context, if available. | |
currentResource (read-only) | The URL of the request. | |
domain (read-only) | The domain of the authentication operation. | |
language | The language code assigned to the client. | |
loginId | The login ID of the client, if provided. This is not validated. | |
requiredRoles (read-only) | A comma-separated list of the roles requested for the user by this request. | |
resource (read-only) | The resource the client wants to access. | |
userId | The user ID assigned to the client in a previous authenticating AuthState . | |
authMarkers (read-only) | Comma-separated list of auth markers of the session (see Auth markers). | |
response | actualRoles (read-only) | A comma-separated list of roles currently assigned to the user. |
error (read-only) | The error code of the last error. | |
errorDetail (read-only) | The details text of the last error. | |
signedTokenAsString (read-only) | The main SecToken issued after authentication, if available. | |
inctx (*) | connection.HttpHeader. <header-name> | HTTP request headers sent by the UserAgent . |
connection.ClientIP | IP address of UserAgent . Subject to configuration of PropagateFromEnv in authentication filter. | |
connection.SSLCipher | SSL cipher used by ClientAgent . Subject to configuration of PropagateFromEnv in authentication filter. | |
connection.actualURL | URL of the current request. | |
sess, session (*) | id (read-only) | Special session variable name that can be used to fetch the session ID. Note that the session ID may change when the initial authentication is completed to reflect the upgrade to authenticated status. |
notes (*) | lastresult | Last result (ResultCond name) selected to reach the current AuthState , if applicable. |
currentstate | Name of the current AuthState . | |
cookie | <cookie name> (read-only) | Access to cookies sent by the client. |
header | <header name> (write-only) | This pseudo-scope allows direct writing of HTTP headers to clients. |
roles | add (write-only) | Pseudo-variable that can be used to add a role to the user's role list. |
remove (write-only) | Pseudo-variable that can be used to remove a role from the user's role list. | |
system | host (read-only) | The default host name. |
time time.<format> (read-only) | The current date and time in GMT syntax. A date format may be given, see documentation of Java's SimpleDateFormat . | |
random random.number.<length> random.bytes.<length> (read-only) | A random number (Java type long ). A length may be given to generate a random number of specific length in digits or a string of random bytes encoded in Base64. | |
litdict | <literal-name> (read-only) | Direct access to localized literal texts (see Language support) |
property | <property name> (read-only) | Access to Java system properties |
oocd | <entry-key> (read-only) | Calls the get(<entry-key>) method of the OutOfContextDataServie and returns the entry. |
(*) Arbitrary variables may be written and read from this scope.