Kerberos authentication AuthStates

Introduction and overview

The Kerberos AuthStates integrate Kerberos authentication based on the simple and protected GSS-API negotiation mechanism (SPNEGO) into nevisAuth. The authentication mechanism is supported by web browsers (Edge, Internet Explorer and Firefox) running under Windows 2000, Windows XP or later versions.

The Kerberos authentication AuthState requires a key distribution center (KDC) in your network (for example, a Windows domain controller with Active Directory) as well as Kerberos-capable clients.

Limitations

The following limitations apply when integrating with Microsoft Active Directory:

• Only DES (type 3) and RC4 (type 23) are supported in combination with the Kerberos ticket extension Privileged Attribute Certificate (PAC). AES128 and AES256 are not supported in combination with the PAC extension.
• Clients must be integrated with the AD Kerberos realm. NTLM (the fallback default of, for example, MSIE6) is not supported. FrontendKerberosAuthState

You typically use the FrontentKerberosAuthState AuthState for password-less logins in internal environments. A sample case is where a user logs in to the workstation and opens a browser, which then loads an application on the intranet without the user having to log in additionally.

The FrontendKerberosAuthState AuthState uses the SPNEGO protocol to receive a SPNEGO init token containing the Kerberos token and ticket from the client (browser). The AuthState then verifies the token based on the Kerberos configuration provided in the AuthState's properties.

The authentication flow goes as follows:

1. The browser, which is integrated with Kerberos, sends a request to nevisAuth.
2. nevisAuth returns the HTTP status code 401 and the response header "WWW-Authenticate: Negotiate", in line with `http://tools.ietf.org/html/rfc4559#section-4.
3. The response header in the return initiates the SPNEGO protocol on the browser side. See also `http://tools.ietf.org/html/rfc4178.
4. The browser authenticates the user using Kerberos. This action is out of scope of nevisAuth.
5. The browser sends the Kerberos token to nevisAuth. The token is included in the request header: "Authorization: Negotiate base64encoded token". See also `http://tools.ietf.org/html/rfc4559#section-5.
6. nevisAuth verifies the client and the token based on the Kerberos configurations in the FrontendKerberosAuthStateAuthState.
7. Upon successful verification, nevisAuth grants access to the protected resource.

The AuthState supports multi-realm setups with cross-realm trust and chains of different FrontentKerberosAuthStates.

Description

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.kerberos.FrontendKerberosAuthState
Logging	Tracing: Kerberos Debugging: -Dsun.security.krb5.debug=true (vmargs.conf, output on stdout or redirected log file)
Auditing	none
Marker	Kerberos: token
Properties (basic)	ServicePrincipal (string or "auto", -)The principal name reflects the fully qualified virtual host name of the access proxy (i.e., the host name in the URL, accessed by the browser client). It has the format HTTP/<hostname>@<REALM>. The Kerberos realm (i.e., the Active Directory domain) needs to be configured in UPPERCASE. It is mandatory to specify the realm.If the special value "auto" is configured, the AuthState will extract the SPN from incoming Kerberos tokens and will look for a suitable credential. Use this feature in scenarios where nevisAuth has to impersonate many SPNs and configuring many AuthStates is not acceptable, or where deciding on the ServicePrincipal to impersonate for a particular request is difficult.
	UserIdFormat (string {full,unqualified}, "full")The format of the user ID set upon successful authentication.

Example:

//Assuming a Kerberos user username@REALM:

full: UserId="username@REALM", LoginId="username@REALM"
unqualified: UserId="username", LoginId="username@REALM"

Topic	Description
	PermittedRealms (whitespace-separated list of realms or "", defaults to realm of principal)Only users from realms listed are allowed. The default allows only users from the realm of the principal (HTTP/hostname@REALM*). An asterisk disables this check and allows authentication of users irrespective of their realm.
	BackendServices .
Properties (special use only)	KerberosJaasModule (qualified class name, "com.sun.security.auth.module.Krb5LoginModule")Java class that implementsjavax.security.auth.spi.LoginModule.
	LoginModule-<option>Options forKerberosJaasModule. In most situations, this property should not be set as theAuthStateinjects all necessary options automatically. For a list of supported options, see(https://docs.oracle.com/javase/6/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html)
	LongTermSharedSecretProvider (qualified class name, "ch.nevis.esauth.auth.states.kerberos.PropertiesFileBasedLongTermSharedSecretProvider")Java class that provides the key material for this AuthState. The key material is security-sensitive and should be protected accordingly.
	LongTermSharedSecretProvider-<option>Options for theLongTermSharedSecretProvider. The property providerPropertiesFileBasedLongTermSharedSecretProvidersupports the following options: *LongTermSharedSecretProvider-Path: Path to the properties file configuring the provider. Default: "/var/opt/nevisauth/<instance>/conf/kerberos-credentials.properties".
Properties (PAC processing)	processPAC(boolean, "false")This property switches on the processing of PAC, a Microsoft extension structure embedded into Kerberos tokens by the Microsoft ActiveDirectory. See the topic "Notes" in this table for a list of propagated data.
	pacMapping(whitespace-separated list of colon-separated key/value pairs, "")When PAC processing is enabled, use this property to define role names for group SIDs. Mapped values will be added to the list of the user's roles. Example:
	includeExtraSids(boolean, "false")In addition to the group SIDs, the extra SIDs will also be processed according to thepacMappingconfigured.
Methods	process
Input	HTTP/Negotiate authentication header If not sent by the client, the AuthState will request the header via nevisProxy. See RFC4559 for details on SPNEGO-based Kerberos authentication.
Transitions	ok: SPNEGO token was successfully checked and the user's identity extracted from it. The user's realm is permitted.ntlm: An NTLM token was found. TheFrontEndKerberosAuthstatedoes not support NTLM and will not do anything except setting the result.failed: In case the token could not be recognized as either SPNEGO or NTLM.default: In any other case. May be used to concatenate multipleKerberosFrontendsAuthStates with differing configuration.
Output	none
Errors	Error code 1 with one of the Kerberos status error messages: NO_STATUS: internal error – status not set SUCCESS_GSS: authenticated successfully at GSS level, further checks needed SUCCESS_OVERALL: authenticated successfully REALM_CHECK_FAILED: The client was authenticated successfully using Kerberos, but it is not in the list of permitted realms. NEGOTIATE_INVALID: The HTTP headerAuthorizationfrom the client is not a valid negotiate header. NTLMSSP: unsupported protocol – NTLMSSP CHECKSUM_FAILED: could not verify thechecksumin the authenticator. Possible causes include: The configured key for the ServicePrincipal is wrong. A setup with multiple keys for thisServicePrincipalis used and only one of the keys will match. A setup with chained FrontendKerberosAuthStates is used. Only one of them will match. The client has an old service ticket in his credentials cache. An attacker is trying an online brute force attack on the service key. OTHER_GSS_ERROR: unknown GSS error ANONYMOUS: Anonymous Kerberos is not allowed.
GUIs	www-authenticate: This GUI is shown during the automatic login process before the browser sends a Negotiate-Token. Normally, this GUI is only visible for a very short time. In the case of a misconfiguration, however, this GUI may be displayed by the browser and can be used to show the reason of the failure. error: This GUI is shown in case the browser sent a Negotiate-Token that was not accepted.
Notes	None by defaultIf processPAC is enabled, the following notes will be set: *kerberos.pac.UserAccountControl: a comma-separated list of flags active in theUserAccountControl field, such as USER_DONT_EXPIRE_PASSWORD, USER_TRUSTED_TO_AUTHENTICATE_FOR_DELEGATION, etc. * kerberos.pac.groupSids: A comma-separated list of the group SIDs of the user. SIDs may be mapped to human-readable values with the property pacMapping. If an SID is mapped by this property, the result will be interpreted as a role and added to the user's list of roles. The following notes are set to the corresponding fields of the PAC:kerberos.pac.badPasswordCount kerberos.pac.resourceGroupSids kerberos.pac.logonCount kerberos.pac.domainName kerberos.pac.groupSid kerberos.pac.homeDirectory kerberos.pac.homeDrive kerberos.pac.kickOffTime kerberos.pac.logoffTime kerberos.pac.lognScript kerberos.pac.logonTime kerberos.pac.profilePath kerberos.pac.pwdLastChangeTime kerberos.pac.pwdMustChangeTime kerberos.pac.serverName kerberos.pac.userDisplayName kerberos.pac.userName kerberos.pac.userSid kerberos.pac.extraSids For more information on the above fields and PAC in general, see MS-PAC, Privilege Attribute Certificate Data Structure, http://msdn.microsoft.com/en-us/library/cc237917.aspx. The flags of the UserAccountControl are described in MS-SAMR, Security Account Manager (SAM) Remote Protocol (Client-to-Server), http://msdn.microsoft.com/en-us/library/cc245476.aspx, chapter 2.2.1.12.

Example A sample configuration is shown and explained in the chapter Integrating with a Kerberos environment - AD. |

BackendKerberosAuthState

This AuthState authenticates the user towards a KDC and expects a ticket-granting ticket (TGT) upon success. With this TGT, the AuthState recontacts the KDC and requests service tickets for each configured backend. The service tickets are then forwarded to nevisProxy for injection by the DelegationFilter as SPNEGO tokens. Kerberos-capable backends receive the tokens in the HTTP header Authorization: Negotiate <token>, which enables them to verify the identity of the user.

Multi-realm setups are not supported.

Tickets have a limited lifetime (per default 10 hours). After this time, the user has to re-authenticate himself again with his user name and password.

Description

The following table describes the characteristics of the AuthState.

Topic	Description
Class	ch.nevis.esauth.auth.states.kerberos.BackendKerberosAuthState
Logging	Tracing: Kerberos Debugging: -Dsun.security.krb5.debug=true (vmargs.conf, output on stdout or redirected log file)
Auditing	none
Properties (basic)	UserNameSource (string, -)This property must evaluate to a user name without realm or protocol. nevisAuth variable expressions may be used.
	RealmSource (string, -)This property must evaluate to the realm without principal or protocol. nevisAuth variable expressions may be used. By convention, realms are written in UPPERCASE.
	PasswordSource for supported encoding mechanisms. The source may also start with "keytab://..." and specify the path to a keytab file containing the key. Passwords should never be specified in the configuration in plaintext.
	TicketFormat (string, "fcc")Possible values are: fcc, java and apreq. Defines the format of the propagated service ticket. fcc is the service ticket format for c. It must be used if nevisProxy delegates the Kerberos ticket.
	UserIdFormat, PermittedRealms, BackendServices, KerberosJaasModule, LoginModule-<option>See the chapter above.
Methods	process
Input	Only values provided by variable substitution
Transitions	ok: successful authentication default: in any other case
Output	none
Errors	*1: username and/or realm not specified 1: This realm is not in the list of permitted realms. 1: Login failed
Notes	none

See Integrating with a Kerberos environment - AD for further details.