---
title: KerberosIdentityAssertionPlugin
description: Use with an IdentityAssertionHandler to validate Kerberos authentication tickets locally.
component: pinggateway
version: 2025.9
page_id: pinggateway:reference:KerberosIdentityAssertionPlugin
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/KerberosIdentityAssertionPlugin.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/KerberosIdentityAssertionPlugin.html
section_ids:
  KerberosIdentityAssertionPlugin-usage: Usage
  KerberosIdentityAssertionPlugin-properties: Properties
  KerberosIdentityAssertionPlugin-config: Kerberos configuration
  KerberosIdentityAssertionPlugin-example: Examples
  KerberosIdentityAssertionPlugin-moreinfo: More information
---

# KerberosIdentityAssertionPlugin

Use with an [IdentityAssertionHandler](IdentityAssertionHandler.html) to validate Kerberos authentication tickets locally.

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

## Usage

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

## Properties

* `"serviceLogin"`: *ServiceLogin [reference](preface.html#definition-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.

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

    * `"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](SecretsProvider.html) 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. |

    ```json
    {
      "type": "KeytabServiceLogin",
      "config": {
        "username": configuration_expression<string>,
        "keytabFile": configuration expression<secret-id>,
        "executor": ScheduledExecutorService reference
      }
    }
    ```

    * `"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](preface.html#definition-reference), optional*

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

      Default: [ScheduledExecutorService](ScheduledExecutorService.html) or an executor service declared in the heap.

- `"trustedRealms"`: *array of configuration expression<[strings](preface.html#definition-string)>, 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](preface.html#definition-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:

  ```json
  {
      "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>"
          }
      }
  }
  ```

  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`.

## Kerberos configuration

When using this plugin, you can use Java system properties or a Kerberos configuration file to provide information about the Kerberos installation.

The following examples use system properties to set the default realm and Key Distribution Center (KDC). The system property settings override any settings found in a Kerberos configuration file:

* Linux

  `export IG_OPTS="-Djava.security.krb5.realm=example.com -Djava.security.krb5.kdc=kdc.example.com"`

* Windows

  `set "IG_OPTS=-Djava.security.krb5.realm=example.com -Djava.security.krb5.kdc=kdc.example.com"`

The following examples reference a Kerberos configuration file for advanced configuration options like encryption types:

* Linux

  `export IG_OPTS="-Djava.security.krb5.conf=/path/to/krb5.conf"`

* Windows

  `set "IG_OPTS=-Djava.security.krb5.conf=\path\to\krb5.conf"`

Learn more in [Define environment variables for startup, runtime, and stop](../installation-guide/envvar-sysprop.html#envvar-sysprop-variables) and in the Java *Security Developer's Guide* [Kerberos Requirements](https://docs.oracle.com/en/java/javase/21/security/kerberos-requirements.html).

## Examples

```json
{
  "type": "KerberosIdentityAssertionPlugin",
  "config": {
    "serviceLogin": "UsernamePasswordServiceLogin",
    "trustedRealms": ["EXAMPLE.COM"]
  }
}
```

```json
{
  "type": "UsernamePasswordServiceLogin",
  "config": {
    "username": "igsa",
    "passwordSecretId": "igsa.id",
    "secretsProvider": "mySecretsProvider"
  }
}
```

Both types require a Service Principal Name (SPN) for the PingGateway service account. The following commands add and view a Service Principal Name (SPN) for the PingGateway service account, `igsa`. Run the commands as the Windows Administrator to ensure you have access to everything necessary:

```powershell
# 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
```

When using a Kerberos keytab file, generate it for PingGateway with the Windows `ktpass` command. The following command generates a keytab file for PingGateway in the `example.com` realm mapped to the `igsa` service account username. Run the command as the Windows Administrator to ensure you have access to everything necessary:

```powershell
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
```

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

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

## More information

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

[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)

The following APIs are used in this class:

* [Kerberos: The Network Authentication Protocol](https://web.mit.edu/kerberos/www/index.html)

* [Kerberos Authentication Overview](https://learn.microsoft.com/en-us/windows-server/security/kerberos/kerberos-authentication-overview)

* [Kerberos Requirements](https://docs.oracle.com/en/java/javase/21/security/kerberos-requirements.html)

* [Single Sign-on Using Kerberos in Java](https://docs.oracle.com/en/java/javase/21/security/single-sign-using-kerberos-java1.html)

* [Java Troubleshooting](https://docs.oracle.com/en/java/javase/21/security/troubleshooting.html)

* [How do I enable debug logging for troubleshooting Kerberos and WDSSO issues in AM (All versions)?](https://support.pingidentity.com/s/article/How-do-I-enable-debug-logging-for-troubleshooting-Kerberos-and-WDSSO-issues-in-PingAM)