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
unauthorizedResponseHandlerprovide 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-Authenticateheader to set it toNegotiate.Default: Return an empty HTTP 401 Unauthorized response with a
WWW-Authenticateheader set toNegotiate.
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 and in the Java Security Developer’s Guide Kerberos Requirements.
Examples
{
"type": "KerberosIdentityAssertionPlugin",
"config": {
"serviceLogin": "UsernamePasswordServiceLogin",
"trustedRealms": ["EXAMPLE.COM"]
}
}{
"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:
# 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.comWhen 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 -out keytab.file -princ HTTP/ig.example.com@EXAMPLE.COM -pass `
+rndPass -maxPass 256 -mapuser igsa -crypto All -ptype KRB5_NT_PRINCIPAL -kvno 0In 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"
}
}