IG 2023.11

PasswordReplayFilter

Extracts credentials from AM and replays them to a login page or to the next filter or handler in the chain. The PasswordReplayFilter does not retry failed authentication attempts.

The PasswordReplayFilter filter uses the AM Post Authentication Plugin com.sun.identity.authentication.spi.JwtReplayPassword. The plugin is triggered for AM authentication chains but not currently for AM authentication trees.

Do not use the PasswordReplayFilter with AM authentication trees.

Usage

{
  "name": string,
  "type": "PasswordReplayFilter",
  "config": {
    "request": object,
    "loginPage": runtime expression<boolean>,
    "loginPageContentMarker": pattern,
    "credentials": Filter reference,
    "headerDecryption": object,
    "loginPageExtractions": [ object, ... ]
  }
}

Properties

"request": <object>, required

The HTTP request message that replays the credentials.

{
  "request": object,
    "method": config expression<string>,
    "uri": runtime expression<string>,
    "version": configuration expression<string>,
    "entity": runtime expression<string>,
    "headers": map,
    "form": map
}

For information about the properties of `request`refer to Request.

The JSON object of request is the config content of a StaticRequestFilter.

"loginPage": runtime expression<boolean>, required unless loginPageContentMarker is defined

true: Direct the request to a login page, extract credentials, and replay them.

false: Pass the request unchanged to the next filter or handler in the chain.

The following example expression resolves to true when the request is an HTTP GET, and the request URI path is /login:

${find(request.uri.path, '/login') and (request.method == 'GET')}
"loginPageContentMarker": pattern, required unless loginPage is defined

A pattern that matches when a response entity is a login page.

For an example route that uses this property, refer to Login form with password replay and cookie filters.

See also Patterns.

"credentials": Filter reference, optional

Filter that injects credentials, making them available for replay. Consider using a FileAttributesFilter or an SqlAttributesFilter.

When this is not specified, credentials must be made available to the request by other means.

See also Filters.

"headerDecryption": object, optional

Object to decrypt request headers that contain credentials to replay.

{
  "headerDecryption": object,
    "algorithm": configuration expression<string>,
    "headers": [ configuration expression<string>, ... ],
    "keySecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference,
    "charset": configuration expression<string>,
    "key": string, //deprecated
    "keyType": string //deprecated
}
"algorithm": configuration expression<string>, optional

Algorithm used for decryption. Use the same algorithm that is used to send the encrypted credentials.

Default: AES/ECB/PKCS5Padding

"headers": array of configuration expression<strings>, optional

The names of header fields to decrypt.

Default: Do not decrypt any headers.

"keySecretId": configuration expression<secret-id>, required

The secret ID of the key to encrypt or decrypt the headers. This property takes precedence over the deprecated property key.

This secret ID must point to a CryptoKey.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to resolve queried secrets, such as passwords and cryptographic keys. For allowed formats, refer to SecretsProvider.

"charset": configuration expression<string>, optional

The name of the charset used to encrypt or decrypt values, as described in Class Charset.

Default: UTF-8

"key": string, optional
The use of this property is deprecated; use keySecretId and secretsProvider instead. For more information, refer to the Deprecated section of the Release Notes.

Base64 encoded key value.

"keyType": string, required
The use of this property is deprecated; use keySecretId and secretsProvider instead. For more information, refer to the Deprecated section of the Release Notes.

Algorithm name for the secret key.

Default: AES

"loginPageExtractions": array of <objects>, optional

Objects to extract values from the login page entity.

{
  "loginPageExtractions": [
    {
      "name": string,
      "pattern": pattern
    },
    ...
  ]
}

For an example route that uses this property, refer to Login which requires a hidden value from the login page.

The extract configuration array is a series of configuration objects. To extract multiple values, use multiple extract configuration objects. Each object has the following fields:

"name": string, required

Name of the field where the extracted value is put.

The names are mapped into attributes.extracted.

For example, if the name is nonce, the value can be obtained with the expression ${attributes.extracted.nonce}.

The name isLoginPage is reserved to hold a boolean that indicates whether the response entity is a login page.

"pattern": pattern, required

The regular expression pattern to find in the entity.

The pattern must contain one capturing group. (If it contains more than one, only the value matching the first group is placed into attributes.extracted.)

For example, suppose the login page entity contains a nonce required to authenticate, and the nonce in the page looks like nonce='n-0S6_WzA2Mj'. To extract n-0S6_WzA2Mj, set "pattern": " nonce='(.*)'".

Example

The following example authenticates requests using static credentials when the request URI path is /login. This PasswordReplayFilter example does not include any mechanism for remembering when authentication has already been successful, it simply replays the authentication every time that the request URI path is /login:

{
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [{
        "type": "PasswordReplayFilter",
        "config": {
          "loginPage": "${request.uri.path == '/login'}",
          "request": {
            "method": "POST",
            "uri": "https://www.example.com:8444/login",
            "form": {
              "username": [
                "MY_USERNAME"
              ],
              "password": [
                "MY_PASSWORD"
              ]
            }
          }
        }
      }],
      "handler": "ReverseProxyHandler"
    }
  }
}

For additional examples, refer to Configuration templates, and the Javadoc for the PasswordReplayFilter class.

Copyright © 2010-2023 ForgeRock, all rights reserved.