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
    }
}

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
  }
}

"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
  }
}

"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>"
        }
    }
}

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

Make sure your firewall allows PingGateway to access the Key Distribution Center (KDC) such as the Active Directory server on port 88 for TCP and UDP.
This plugin can rely on 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 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"

The following example krb5.conf file shows important configuration options for a PingGateway system where the Kerberos realm is EXAMPLE.COM and the KDC is kdc.example.com:
[libdefaults] default_realm = EXAMPLE.COM [realms] EXAMPLE.COM = { kdc = kdc.example.com admin_server = kdc.example.com } [domain_realm] .example.com = EXAMPLE.COM example.com = EXAMPLE.COM
Learn more in Define environment variables for startup, runtime, and stop and in the Java Security Developer’s Guide Kerberos Requirements.
Increase the maxTotalHeadersSize in admin.json for external connections as the Kerberos Ticket Granting Ticket (TGT) is larger than the default (8192 bytes).

The following example sets the maxTotalHeadersSize to 56192 bytes, 48 KB for the TGT plus the default for other headers:
```
{
  "connectors": [
    {
      "maxTotalHeadersSize": 56192
    }
  ]
}
```
Make sure you restart PingGateway after updating admin.json to load the changes.

Browser configuration

For Windows Desktop SSO to work correctly with Kerberos, make sure:

The lists of trusted hosts in the browser settings includes the PingGateway FQDN.
The Service Principal Name (SPN) for the PingGateway service account is correctly configured.

With Microsoft Edge, also make sure:

The service you access uses HTTP persistent connections.

As of HTTP 1.1, connections are persistent by default.
The browser has Integrated Windows Authentication enabled.
The browser has Automatic logon with current username and password enabled.
The Windows Defender Credential Guard is disabled in the Windows firewall.
The browser restarts after you make configuration changes.

With Google Chrome, also make sure:

If the browser inherits settings from Microsoft Edge, it works when Microsoft Edge is correctly configured.
Otherwise, learn more in How do I set up Kerberos authentication in PingAM?

With Mozilla Firefox, also make sure:

The network.negotiate-auth.trusted-uris and network.automatic-ntlm-auth.trusted-uris settings include the PingGateway FQDN or hostname suffix, like .example.com.

You can view the values in about:config.
For Kerberos SSO with private browsing, also set network.auth.private-browsing-sso to true.

Apple Safari has built-in support for Kerberos SSO. No additional configuration is necessary.

Examples

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

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

Both types require an SPN for the PingGateway service account. The following commands add and view an SPN for the PingGateway service account, igsa. Run the commands as the Windows Administrator to ensure you have access to everything necessary.

The hostname in this example, ig.example.com, is the one the browser uses to access PingGateway:

# 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:

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

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"
  }
}

Troubleshooting

When setting IG_OPTS system properties for troubleshooting, you can also enable debugging with the following options:

-Dsun.security.krb5.debug=true
-Dsun.security.spnego.debug=true
-Dsun.security.jgss.debug=true

With these settings, PingGateway writes the Kerberos debug messages to standard output.

To write additional messages to a log file, update the PingGateway logback.xml file with a setting such as the following:

<logger name="org.forgerock.openig.assertion" level="TRACE" />

Restart PingGateway unless you configured Logback to automatically scan for configuration changes.

The TRACE log level produces very detailed output. Learn about log levels in Changing the log level for different object types.

PingGateway