---
title: Scripted module API (deprecated)
description: 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.
component: pingam
version: 7.5
page_id: pingam:am-authentication:scripting-api-authn
canonical_url: https://docs.pingidentity.com/pingam/7.5/am-authentication/scripting-api-authn.html
keywords: ["Authentication", "Sessions", "Modules & Chains", "Scripting"]
page_aliases: ["authentication-guide:scripting-api-authn.adoc"]
section_ids:
  scripting-api-authn-state: Authentication state
  scripting-api-authn-id-repo: Profile data
  client_side_script_output_data: Client-side script output data
  scripting-api-authn-request-data: Request data
  scripting-api-node-gotoonfailure: Redirect users after authentication failure
---

# Scripted module API (deprecated)

In addition to the functionality provided by the [HTTP client](../am-scripting/script-bindings.html#httpclient) and the [logging API](../am-scripting/script-bindings.html#logger), authentication modules that use server-side scripts can access the authentication state of a request, information about the session, and the login request itself.

|   |                                                                                                                                                                                                                                                    |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Authentication modules and chains are deprecated and will be removed in a future release. Convert existing authentication journeys that use modules and chains to [authentication nodes and trees](about-authentication-trees.html) when possible. |

Client-side scripts in modules gather data into a string that's returned to AM in a self-submitting form.

If you're 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.

Learn more in the [org.forgerock.allow.http.client.debug](../reference/deployment-configuration-reference.html#appenders-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

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

```javascript
...
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](redirection-url-precedence.html#configure-validation-service) of the realm; otherwise, AM ignores the redirect.