Scripted Module API Functionality

In addition to the functionality provided by the "Accessing HTTP Services" and "Debug Logging", authentication modules that use server-side scripts can access the authorization state of a request, the information pertaining a 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.

Tip

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 API functionality includes:

Accessing 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
Windows Desktop SSO

Accessing 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.

Accessing 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.

Accessing Request Data

Server-side scripts can get access to 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.

Redirecting the User 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:

...
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 will ignore the redirection. For more information, see "To Configure the Validation Service".