Skip to main content
Version: 8.2405.x.x RR

Kerberos Integration

Kerberos Login​

Experimental

The Kerberos Login authentication scenario is using the experimental KerberosLoginAuthState. This new auth state replaces the deprecated Kerberos implementation.

In the Kerberos Login authentication scenario nevisAuth uses long-term Kerberos keys to validate Kerberos Service Tickets issued by the Kerberos Key Distribution Center (KDC) and —together with nevisProxy— provide access for authorized clients to non-Kerberized backend services.

The following figure shows the Kerberos Login authentication scenario:

Kerberos login scenario

Kerberos Login Integration​

The following steps are needed to integrate a backend service into a Kerberos realm:

  1. Register a Service Principal Name (SPN) at the Key Distribution Center (KDC) of the Kerberos realm. Use the following SPN format: HTTP/<hostname>[:port] where:
  • <hostname> is the fully-qualified virtual host name of the access proxy
  • [:port] is an optional port number
  1. Generate a keytab file containing the long-term Kerberos key belonging to the SPN and make it accessible to nevisAuth. This is the point where the used encryption types could be defined, see also supported encryption types.
  2. Configure the KerberosLoginAuthState to use the keytab file as a kerberos credential, for further details please consult KerberosLoginAuthState

For further details regarding how to register an SPN at the KDC or how to generate a keytab file with specific encryption types please consult the documentation of the used Kerberos KDC.

Supported Encryption Types​

In general, it is recommended to use the most secure encryption type(s) supported by all involved parties like the client platform (OS and browser), Kerberos KDC and nevisAuth.

The nevisAuth implementation of the Kerberos Login scenario is based on the Java Generic Security Services (Java GSS) for Kerberos 5 feature of the JVM which also determines the set of the supported encryption types form its side. For further details please consult the JVM documentation: The Kerberos 5 GSS-API Mechanism

Regarding the supported encryption types by the Kerberos KDC and by the client platform please consult the documentation of the used products.

Integrating with a Kerberos environment - AD​

Deprecated

Kerberos authentication scenarios using FrontendKerberosAuthState and/or the BackendKerberosAuthState are deprecated and will be removed with the November 2023 release, use the KerberosLoginAuthState based integration instead.

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 and BackendKerberosAuthState.

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 figure below, go to the Account options section and make the following required settings:
  • Deactivate User must change password at next logon.
  • Activate Password never expires.
  • Select This account supports Kerberos AES 128 bit or This account supports Kerberos AES 256 bit (see also Encryption types).
  1. If you want to use pass-through authentication, go to the Delegation tab of the Properties window.
  • Either activate the option Trust this user for delegation to any service (Kerberos only), or
  • List the applications, which Nevis should be allowed to delegate to, under Trust this user for delegation to specified service only.
Properties window - Example user configuration

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
info

The MS Internet Explorer will need to request the following principal name: "HTTP/[email protected]".

info

In the previous figure, 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
info

Be sure to respect the case (that is, the REALM is usually in capital letters).

  1. Make sure that the principal name of the host is not used yet (expect empty output):

    setspn -L %ACCOUNT%

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

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

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

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

info

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:

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

Kerberos configuration scenarios

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

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.

info

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

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.

caution

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.

    info

    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:

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