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
SecurID
Windows Desktop SSO
Accessing Profile Data
Server-side authentication scripts can access profile data through the methods of the idRepository object.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| | | | Return the values of the named attribute for the named user. |
| | | | Set the named attribute as specified by the attribute value for the named user, and persist the result in the user's profile. |
| | | | 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.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| | | | Return the String value of the named request header, or |
| | | | Return the array of String values of the named request header, or |
| | | | Return the String value of the named request parameter, or |
| | | | Return the array of String values of the named request parameter, or |
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".