PingGateway 2025.3

KerberosIdentityAssertionPlugin

Use with an IdentityAssertionHandler to validate Kerberos authentication tickets locally.

The KerberosIdentityAssertionPlugin doesn’t support Windows New Technology LAN Manager (NTLM) tokens.

Usage

{
    "name": string,
    "type": "KerberosIdentityAssertionPlugin",
    "config": {
      "serviceLogin": ServiceLogin reference,
      "trustedRealms": [configuration_expression<string>, ...],
      "unauthorizedResponseHandler": Handler reference
    }
}
json

Properties

"serviceLogin": ServiceLogin reference, required

A service account object to log PingGateway in to the Kerberos server so that PingGateway can act on user tokens. PingGateway will be able to validate user tokens, for example.

PingGateway provides the following service account objects for the KerberosIdentityAssertionPlugin:

UsernamePasswordServiceLogin

Log PingGateway in to the Kerberos server by using a service account username and password.

{
  "type": "UsernamePasswordServiceLogin",
  "config": {
    "username": configuration_expression<string>,
    "passwordSecretId": configuration expression<secret-id>,
    "secretsProvider": SecretsProvider reference
  }
}
json
"username": configuration expression<string>, required

Service username.

"passwordSecretId": configuration expression<secret-id>, required if the proxy requires authentication

The secret ID of the service account password.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for the password.

KeytabServiceLogin

Log PingGateway in to the Kerberos server by using a Keytab file.

This service account object is less secure than UsernamePasswordServiceLogin; use it only for testing or to ease migration. In production environments, always use the most secure options available. 
{
  "type": "KeytabServiceLogin",
  "config": {
    "username": configuration_expression<string>,
    "keytabFile": configuration expression<secret-id>,
    "executor": ScheduledExecutorService reference
  }
}
json
"username": configuration expression<string>, required

Service username.

"keytabFile": configuration expression<string>, required

Path to the keytab file. Both the username and keytabFile are required for login.

"executor": ScheduledExecutorService reference, optional

An executor service to schedule the execution of tasks during a keytab service login.

Default: ScheduledExecutorService or an executor service declared in the heap.

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

A list of one or more Kerberos realms that are expected to match the principal’s realm from the user’s Kerberos ticket.

Kerberos tickets are accepted only if the principal’s realm matches a realm in the list.

Default: Empty

"unauthorizedResponseHandler": handler reference, optional

Override the default unauthorized handler.

When a browser can’t supply a Kerberos token and isn’t configured to deal appropriately with HTTP 401 Unauthorized, the default response can leave the user stuck on an unauthorized page. Use the unauthorizedResponseHandler provide an appropriate response, such as the following:

{
    "unauthorizedResponseHandler": {
        "type": "StaticResponseHandler",
        "config": {
            "status": 401,
            "headers": {
                "Content-Type": [
                    "text/html; charset=UTF-8"
                ]
            },
            "entity": "<!DOCTYPE html><html><head><title>401 Unauthorized</title></head><body><form method=\"POST\"><input type=\"submit\" value=\"Return to Sign In\" /></form></body></html>"
        }
    }
}
json

When you use a custom handler, PingGateway overrides the response status to set it to HTTP 401 Unauthorized and overrides WWW-Authenticate header to set it to Negotiate.

Default: Return an empty HTTP 401 Unauthorized response with a WWW-Authenticate header set to Negotiate.

Examples

{
  "type": "KerberosIdentityAssertionPlugin",
  "config": {
    "serviceLogin": "UsernamePasswordServiceLogin",
    "trustedRealms": ["EXAMPLE.COM"]
  }
}
json
{
  "type": "UsernamePasswordServiceLogin",
  "config": {
    "username": "igsa",
    "passwordSecretId": "igsa.id",
    "secretsProvider": "mySecretsProvider"
  }
}
json

When using a Kerberos keytab file, generate it for PingGateway with the Windows ktpass command. The following commands add and view a Service Principal Name (SPN) for the PingGateway service account, igsa, and generate a keytab file for PingGateway in the example.com realm mapped to the service account username. Run the commands as the Windows Administrator to ensure you have access to everything necessary:

# Add the SPN for the service account:
PS C:\path\to> setspn -s HTTP/ig.example.com igsa

# View the SPN for the service account:
PS C:\path\to> setspn -l igsa
Registered ServicePrincipalNames for CN=igsa,CN=Users,DC=example,DC=com:
        HTTP/ig.example.com

# Generate the keytab file:
PS C:\path\to> ktpass -out keytab.file -princ HTTP/ig.example.com@EXAMPLE.COM -pass `
+rndPass -maxPass 256 -mapuser igsa -crypto All -ptype KRB5_NT_PRINCIPAL -kvno 0
powershell

In the PingGateway configuration, you can use the Kerberos principal as the username:

{
  "type": "KeytabServiceLogin",
  "config": {
    "username": "HTTP/ig.example.com@EXAMPLE.COM",
    "keytabFile": "/path/to/keytab.file"
  }
}
json

More information

org.forgerock.openig.assertion.plugin.kerberos.KerberosIdentityAssertionPlugin

org.forgerock.openig.assertion.plugin.IdentityAssertionPlugin

org.forgerock.openig.handler.assertion.IdentityAssertionClaims

The following APIs are used in this class: