---
title: ScriptableIdentityAssertionPlugin
description: An out-of-the box implementation of IdentityAssertionPlugin to support use-cases that aren't provided by a PingGateway plugin.
component: pinggateway
version: 2026
page_id: pinggateway:reference:ScriptableIdentityAssertionPlugin
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ScriptableIdentityAssertionPlugin.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  ScriptableIdentityAssertionPlugin-usage: Usage
  ScriptableIdentityAssertionPlugin-properties: Properties
  ScriptableIdentityAssertionPlugin-example: Example
  ScriptableIdentityAssertionPlugin-moreinfo: More information
---

# ScriptableIdentityAssertionPlugin

An out-of-the box implementation of [IdentityAssertionPlugin](../_attachments/apidocs/org/forgerock/openig/assertion/plugin/IdentityAssertionPlugin.html) to support use-cases that aren't provided by a PingGateway plugin.

Use with an [IdentityAssertionHandler](IdentityAssertionHandler.html) for local processing, such as authentication. The plugin returns [IdentityAssertionClaims](../_attachments/apidocs/org/forgerock/openig/assertion/IdentityAssertionClaims.html) to include in the identity assertion JWT PingGateway sends to PingOne Advanced Identity Cloud.

The script does the following:

1. Validates the identity request JWT.

2. (Optional) Takes a single String that represents the principal or a principal and a map of additional claims from the [IdentityRequestJwtContext](IdentityRequestJwtContext.html).

3. If a PreProcessingFilter is configured, triggers the filter.

4. Returns principal and identity claims in the identity assertion JWT.

If script execution fails, the plugin creates an IdentityAssertionPluginException.

## Usage

```json
{
    "name": string,
    "type": "ScriptableIdentityAssertionPlugin",
    "config": {
        "preProcessingFilter": Filter reference,
        "type": configuration expression<string>,
        "file": configuration expression<string>, // Use either "file"
        "source": [ string, ... ],                // or "source", but not both
        "args": map,
        "clientHandler": Handler reference
    }
}
```

## Properties

For information about other properties for ScriptableIdentityAssertionPlugin, refer to [PingGateway scripts](Scripts.html).

* `"preProcessingFilter"`: *\_Filter [reference](preface.html#definition-reference), optional*

  A [Filter](Filters.html) to perform user defined actions, such as local authentication and/or authorization.

  Default: Pass the request without pre-processing.

## Example

The following example applies a `preProcessingFilter` that uses a ScriptableFilter to test whether the user is authenticated. If a Basic Authorization Header isn't found, a response is generated to trigger a Basic Authentication.

```
{
  "name": "BasicAuthScriptablePlugin",
  "type": "ScriptableIdentityAssertionPlugin",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "import org.forgerock.openig.handler.assertion.IdentityAssertionClaims",
      "import org.forgerock.openig.handler.assertion.IdentityAssertionException",
      "if (request.headers.authorization != null && request.headers.authorization.values[0] == 'Basic user:password') {",
          return new IdentityAssertionClaims("iguser", Map.of("auth", "basic"))",
      "}",
      "return newExceptionPromise(new IdentityAssertionException('Invalid authentication'))",
    ],
    "preProcessingFilter": {
      "type": "ScriptableFilter",
      "config": {
        "type": "application/x-groovy",
        "source": [
          "if (request.headers.authorization == null) {",
          "    Response response = new Response(Status.UNAUTHORIZED)",
          "    response.headers['WWW-Authenticate'] = \"Basic\"",
          "    return response",
          "}",
          "return next.handle(context, request)",
        ],
      },
    }
  }
}
```

## More information

[org.forgerock.openig.assertion.plugin.IdentityAssertionPlugin](../_attachments/apidocs/org/forgerock/openig/assertion/plugin/IdentityAssertionPlugin.html)

[org.forgerock.openig.assertion.IdentityAssertionClaims](../_attachments/apidocs/org/forgerock/openig/assertion/IdentityAssertionClaims.html)