Integrating with a Kerberos environment - AD

Integrating nevisAuth with an Active Directory (AD) Kerberos realm includes the following activities:

• Registering the access infrastructure (nevisProxy host) with the AD.
• Generating a key to be installed with nevisAuth (or share the secret to be used for the generation of the key with nevisAuth).
• Configuring nevisAuth.
• Optionally: Configuring nevisProxy to forward Kerberos tokens to applications.

The following guidelines use the AuthStates FrontendKerberosAuthState .

Step 1: Registering the proxy host in AD

Use the active directory administration to register a new (functional) user, representing the proxy virtual host. Proceed as follows:

1. When registering the new user, enter a user login name. For example, HTTP/<proxy-host-name>, where <proxy-host-name> is the hostname used by the clients.

2. Set a password (to be used for the key export later).

3. In the Account tab of the user's Properties window (see the, go to the Account options section and make the following required settings:

4. Deactivate User must change password at next logon.

5. Activate Password never expires.

6. Select This account supports Kerberos AES 128 bit or This account supports Kerberos AES 256 bit (see also Encryption types].

7. If you want to use pass-through authentication, go to the Delegation tab of the Properties window.

8. Either activate the option Trust this user for delegation to any service (Kerberos only), or

9. List the applications, which Nevis should be allowed to delegate to, under Trust this user for delegation to specified service only.

Step 2: Activating a Service Principal / Exporting the key

On the Windows machine running the Kerberos key distribution center KDC, proceed as follows:

1. Make sure that you have the required tools and data at hand. This includes the user account name, the fully qualified hostname and the name of the Kerberos realm (that is, the Active Directory domain name).
2. Execute the following commands:

set PATH=%PATH%;"C:\Program Files\Support Tools"
set ACCOUNT=pre-windows-2000 name
set DOMAIN=domain for pre-windows-2000 name
set HOST=entrysv
set FQHN=%HOST%.company.com
set REALM=REALM.COM

The MS Internet Explorer will need to request the following principal name: "HTTP/[email protected]".In the, the following variables would have been set:

PATH=%PATH%;"C:\Program Files\Support Tools"
ACCOUNT=adnws152-cc
HOST=adnws152-c
FQHN=adnws152-c.zh.adnovum.ch
REALM=CTX.LOCAL

Be sure to respect the case (that is, the REALM is usually in capital letters). 3. Make sure that the principal name of the host is not used yet (expect empty output):

 setspn -L %ACCOUNT%

4. Set the principal name for the proxy host account and verify that it was set:

setspn -A HTTP/%FQHN% %ACCOUNT%
setspn -L %ACCOUNT%

5. Export the key:

ktpass -princ HTTP/%FQHN%@%REALM% \
 -pass <account-password> -mapuser %DOMAIN%\%ACCOUNT% \
 -out c:\temp%HOST%_HTTP.keytab \
 -ptype KRB5_NT_PRINCIPAL -crypto AES128-SHA1

6. Register the password or the keytab file in kerberos-credentials.properties. The entry should have the form HTTP/<hostname>@<REALM>=<secret>, where <secret> can be any syntax described in chapter Passwords in the configuration. It may also reference the keytab file generated in the previous step with the syntax keytab://<path-to-file>.

Make sure that the data just created is propagated between Active Directory replicas. To trigger this, initiate a manual password change on the functional user account. If this is not done, the Kerberos login may not work, usually resulting in the MS Internet Explorer to send an NTLM token (instead of an SPNEGO/Kerberos token).Step 3: Configuring nevisAuth

The next step is to configure nevisAuth for the integration with Kerberos. How you do this, depends on which authentication scenario you want to use. There are several authentication scenarios:

• Front-end authentication scenario
• Backend authentication scenario
• Pass-through authentication scenario

The following figure shows Nevis / Kerberos configuration for each authentication scenario:

The next sections show how to implement the scenarios.

Front-end authentication scenario

In the front-end authentication scenario, clients authenticate towards a Nevis setup and integrated applications using authentication mechanisms other than Kerberos. Within nevisAuth, the FrontendKerberosAuthState AuthState is responsible for requesting, validating and consuming the Kerberos token sent by the client. No special configuration is required in nevisProxy.

Perform the following steps to implement this scenario:

1. Configure a FrontendKerberosAuthState AuthState as follows:

<AuthState name="KerberosAuthentication"
  class="ch.nevis.esauth.auth.states.kerberos.FrontendKerberosAuthState"
  authLevel="auth.weak" final="false">
 <ResultCond name="ok" next="AuthDone"/>
 <Response value="AUTH_ERROR" >
  <Gui name="error">
   <GuiElem name="info" type="info" label="Authentication failed"/>
  </Gui>
 </Response>
 <property name="ServicePrincipal" value="HTTP/[email protected]"/>
</AuthState>

2. Adapt the default_realm setting in the java-krb5.conf file:

...
default_realm = INTRA.LOCAL
...

3. Register the secret for the principal in the kerberos-credentials.properties (the following example shows the "secret://.." syntax using obfuscation):

 ...
HTTP/[email protected] = secret://e5d32v5
...

Backend authentication scenario

In the backend authentication scenario, clients do not authenticate with Kerberos, but the nevisProxy uses Kerberos to forward the authentication towards applications. Within nevisAuth, the BackendKerberosAuthState AuthState fetches the required tickets from a KDC on behalf of the client. Within nevisProxy, a DelegationFilter handles the injection of the Kerberos HTTP headers into requests to applications. To impersonate the client towards the KDC, nevisAuth requires the user's password.

Perform the following steps to implement this scenario:

1. Configure a BackendKerberosAuthState AuthState as follows:

<AuthState name="KerberosBackend" class="ch.nevis.esauth.auth.states.kerberos.BackendKerberosAuthState" authLevel="auth.weak">
 <ResultCond name="ok" next="AuthDone"/>
 <Response value="AUTH_CONTINUE" >
  <Gui name="AuthUidPwDialog">
   <GuiElem name="username" type="text" label="userid.label" value="${inargs:username}"/>
   <GuiElem name="password" type="pw-text" label="password" value="" />
   <GuiElem name="submit" type="button" label="login.button.label" value="Login"/>
  </Gui>
 </Response>
 <property name="UserNameSource" value="${inargs:username}" />
 <property name="RealmSource" value="INTRA.LOCAL" />
 <property name="PasswordSource" value="${inargs:password}" />
 <property name="UserIdFormat" value="unqualified" />
 <property name="PermittedRealms" value="INTRA.LOCAL" />
 <property name="BackendServices" value=" HTTP/[email protected] "/>
</AuthState>

2. In the java-krb5.conf file, adapt the setting default_realm and register the KDCs:

...
default_realm = INTRA.LOCAL
...
[realms]
...
INTRA.LOCAL = {
 kdc = active-directory.company.com:88
}
...

3. Configure nevisProxy such that Kerberos tokens are injected into the requests going to the applications. Therefore, the following DelegationFilter should be mapped to the location of the application, after the IdentityCreationFilter:

<filter>
 <filter-name>KerberosFilter</filter-name>
 <filter-class>ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>

 <init-param>
  <param-name>Kerberos.Delegation</param-name>
  <param-value>
   HTTP/[email protected]
  </param-value>
 </init-param>
</filter>

When using Kerberos delegation, we strongly recommend configuring the backend connector in nevisProxy as follows:

• KeepAlive=true and KeepAlive.ByClient=true, or
• Disable KeepAlive entirely.

Pass-through authentication scenario

The pass-through scenario incorporates both front-end and backend Kerberos authentication. The client authenticates towards Nevis using Kerberos and authentication is proven to applications using Kerberos as well. Within nevisAuth, the AuthState FrontendKerberosAuthState is responsible for requesting, validating and consuming the Kerberos token sent by the client. The AuthState uses the Kerberos token to fetch from the KDC all tokens required to access the applications. Within nevisProxy, a DelegationFilter injects these tokens into requests issued by the client.

To allow nevisAuth to act as an intermediary between clients and applications, the option Trust this user for delegation to any service (Kerberos only) must be activated for the technical user. You set this option in the Account tab of the user's Active Directory Properties window. See also Registering the proxy host in AD.Perform the following steps to implement this scenario:

1. Configure a Front**endKerberosAuthState AuthState as shown below. This AuthState configuration both authenticates the user and fetches tokens required for accessing backend applications:

<AuthState name="KerberosAuthentication"
    class="ch.nevis.esauth.auth.states.kerberos.FrontendKerberosAuthState"
    authLevel="auth.weak" final="false">
 <ResultCond name="ok" next="AuthDone"/>
 <Response value="AUTH_ERROR" >
  <Gui name="error">
   <GuiElem name="info" type="info" label="Authentication failed"/>
  </Gui>
 </Response>
 <property name="ServicePrincipal" value="HTTP/[email protected]"/>
 <property name="PermittedRealms" value="INTRA.LOCAL" />
 <property name="BackendServices" value=" HTTP/[email protected] "/>
</AuthState>

2. In the java-krb5.conf file, adapt the setting default_realm and register the KDCs:

...
default_realm = INTRA.LOCAL
...
[realms]
...
INTRA.LOCAL = {
  kdc = active-directory.company.com:88
}
...

3. Register the secret for the principal in the kerberos-credentials.properties (the following example shows the "secret://.." syntax using obfuscation):

...
HTTP/[email protected] = secret://e5d32v5
...

4. Configure nevisProxy such that Kerberos tokens are injected into the requests going to the applications. Therefore, the following DelegationFilter should be mapped to the location of the application, after the IdentityCreationFilter:

<filter>
 <filter-name>KerberosFilter</filter-name>
 <filter-class>ch::nevis::isiweb4::filter::delegation::DelegationFilter</filter-class>

 <init-param>
  <param-name>Kerberos.Delegation</param-name>
  <param-value>
    HTTP/[email protected]
  </param-value>
 </init-param>
</filter>

When using Kerberos delegation, we strongly recommend configuring the backend connector in nevisProxy as follows:

• KeepAlive=true and KeepAlive.ByClient=true, or
• Disable KeepAlive entirely. Step 4: Specifying the java-krb5.conf file

The java-krb5.conf configuration file defines the properties of the underlying crypto library (sun.security.krb5). Only one configuration file per nevisAuth instance can be used, but the format allows multiple Frontend-/BackendAuthStates to be used nevertheless.

The DelegationFilter in nevisProxy uses a very similar configuration file when delegating Kerberos tokens. However, the two configuration files are not compatible and the configuration must be strictly separated.

When configuring the java-krb5.conf configuration file, pay attention to the following:

• For the front-end authentication setup including the AuthState FrontendKerberosAuthState, and without pass-through authentication, at least specify the default_realm setting in the libdefaults section of the java-krb5.conf file. The rest is optional. However, we recommend adding the crypto entries to the file as well, to disable DES completely.
• For the backend authentication setup including the AuthState BackendKerberosAuthState as well as the pass-through authentication setup, at least specify a KDC entry per realm. Also, the crypto entries are a must.

It is also possible to specify the AD via DNS, instead of through the KDC entry. However, we do not recommend this.

The following example shows how to configure the java-krb5.conf configuration file:

# example java-krb5.conf ; not heimdal-compatible
[libdefaults]

# disallow DES:
default_tkt_enctypes = aes128-cts rc4-hmac arcfour-hmac arcfour-hmac-md5
default_tgs_enctypes = aes128-cts rc4-hmac arcfour-hmac arcfour-hmac-md5
permitted_enctypes = aes128-cts rc4-hmac arcfour-hmac arcfour-hmac-md5

default_realm = CTX.LOCAL
kdc_timeout = 2000
[realms]
CTX.LOCAL = {
  #kdc: required for backend and pass-through scenarios
  kdc = url.to.kdc.company.ch
}

Encryption types

The following list shows the available encryption types and whether they are supported in the basic Kerberos use cases:

• DES: Not recommended.
• 3DES: Not recommended.
• RC4: Not recommended. Supported for backwards compatibility with older Windows Servers.
• AES128: Supported and default.
• AES256: Supported if an unlimited_strength JRE is used. Compatible with Windows Vista, Windows Server 2008 and Windows 7.

Limitations

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.

Debugging

Implement the following settings to facilitate debugging:

• To find out what the browser sends, use a local proxy on the test client or a browser plug-in (e.g., Fiddler for MSIE and TamperData for Firefox).
• To find out what the proxy requests and receives, enable IsiwebOp=4 tracing in nevisProxy.
• To find out what is forwarded to the nevisAuth server, enable AuthEngine tracing.
• To log the Kerberos and the SPNEGO subsystems of the JVM into stdout, set -Dsun.security.krb5.debug=true and -Dsun.security.spnego.debug=true.

Common problems (shown in the nevisAuth server log) are:

Error	Cause
AuthenticationException: Unrecognized SPNEGO Token	Browser most likely sends an NTLM token, which means, that the PC client is not correctly integrated with the KDC. Use "kerbtray" to check for the acquired kerberos service tickets.
AuthAudit: no kerberos credentials	Proxy called authentication without fetching the SPNEGO token from the client.
GSSException: Failure unspecified at GSS-API level (Mechanism level: Integrity check on decrypted field failed (31))	They secret key is not correct, check "ktpass" generation above and use "kerbtray" to check, how the ticket was encrypted.
GSSException: Channel binding mismatch (Mechanism level: ChannelBinding not provided)	This error happens because of a bug in the Java JDK. As workaround, the following registry key should b e set on the client host: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\SuppressExtendedProtection (REG_DWORD, value=2)