Scripted module API

In addition to the functionality provided by the HTTP client and the logging API, authentication modules that use server-side scripts can access the authentication state of a request, information about the session, and the login request itself.

Client-side scripts in modules gather data into a string, which is returned to AM in a self-submitting form.

When developing server-side scripts, it can be useful to increase the debug level of the org.apache.http.wire and org.apache.http.headers appenders to Message.

By default, these appenders are always set to the Warning level unless logging is disabled. For more information, see the org.forgerock.allow.http.client.debug advanced server property.

Authentication state

AM passes authState and sharedState objects to server-side scripts in order for the scripts to access authentication state.

Server-side scripts can access the current authentication state through the authState object.

The authState value is SUCCESS if the authentication is currently successful, or FAILED if authentication has failed. Server-side scripts must set a value for authState before completing.

If an earlier authentication module in the authentication chain has set the login name of the user, server-side scripts can access the login name through username.

The following authentication modules set the login name of the user:

Anonymous
Certificate
Data Store
Federation
HTTP Basic
JDBC
LDAP
Membership
RADIUS
SecurID
Windows Desktop SSO

Profile data

Server-side authentication scripts can access profile data through the methods of the idRepository object.

Profile data methods
Method	Parameters	Return Type	Description
`idRepository.getAttribute`	`User Name` (type: `String`) `Attribute Name` (type: `String`)	`Set`	Return the values of the named attribute for the named user.
`idRepository.setAttribute`	`User Name` (type: `String`) `Attribute Name` (type: `String`) `Attribute Values` (type: `Array`)	`Void`	Set the named attribute as specified by the attribute value for the named user, and persist the result in the user’s profile.
`idRepository.addAttribute`	`User Name` (type: `String`) `Attribute Name` (type: `String`) `Attribute Value` (type: `String`)	`Void`	Add an attribute value to the list of attribute values associated with the attribute name for a particular user.

Client-side script output data

Client-side scripts add data they gather into a string object named clientScriptOutputData. Client-side scripts then cause the user-agent automatically to return the data to AM by HTTP POST of a self-submitting form.

Request data

Server-side scripts can access the login request by using the methods of the requestData object.

The following table lists the methods of the requestData object. Note that this object differs from the client-side requestData object and contains information about the original authentication request made by the user.

Request data methods
Method	Parameters	Return Type	Description
`requestData.getHeader`	`Header Name` (type: `String`)	`String`	Return the String value of the named request header, or `null` if parameter is not set.
`requestData.getHeaders`	`Header Name` (type: `String`)	`String[]`	Return the array of String values of the named request header, or `null` if parameter is not set.
`requestData.getParameter`	`Parameter Name` (type: `String`)	`String`	Return the String value of the named request parameter, or `null` if parameter is not set.
`requestData.getParameters`	`Parameter Name` (type: `String`)	`String[]`	Return the array of String values of the named request parameter, or `null` if parameter is not set.

Redirect users after authentication failure

Server-side scripts can redirect the user to a specific URL in case of authentication failure by adding a gotoOnFailureUrl property to the chain’s shared state.

When the script reaches a FAILED authentication state (defined by the authState variable), it checks if the gotoOnFailureUrl property is stored in the shared state. If so, the script redirects the user to the specified URL.

You can redirect the user to a page relative to AM’s URL, or to an absolute URL:

Relative URL
Absolute URL

...
sharedState.put("gotoOnFailureUrl","/am/XUI/?service=testChain#failedLogin");
authState = FAILED;
...

...
sharedState.put("gotoOnFailureUrl","http://www.example.com");
authState = FAILED;
...

Note that the failure URL relative to AM’s domain includes the authentication service; this is so that when the user clicks on the link to log in again, AM constructs the login page with the appropriate service instead of with the default one for the realm.

When redirecting the user to an absolute URL different from AM’s scheme, FQDN, and port, you must configure the URL in the validation service of the realm; otherwise, AM ignores the redirect.