Product Selector

Fusion 5.12
    Fusion 5.12

    Set Up Kerberos Authentication

    The Kerberos security provider for Appkit allows authentication using Kerberos. With this provider configured, an application deployed within a Kerberos 'realm' can securely authenticate a user against a Kerberos 'Key Distribution Center'. This module is primarily intended to simplify the process of authenticating a user silently in a Windows environment by leveraging the built in support for integrated Windows authentication in Internet Explorer. However it should be possible to use this module to authenticate the user in any Kerberos compliant environment.

    This guide focuses on how to set up Kerberos authentication within an Appkit application in a Windows environment. It assumes Kerberos is enabled and already working on a domain controller.

    1 Add the security provider dependency

    Authentication against Kerberos requires the Kerberos provider module. To enable this module first remove any existing security provider dependency from the pom.xml under the root of the project and add this within the dependencies tag:

    <dependency>
    <groupId>twigkit</groupId>
    <artifactId>twigkit.security.provider.kerberos</artifactId>
    <version>${project.parent.version}</version>
</dependency>

    Then to configure Appkit to invoke this module on startup change the security.conf file in src/main/resources/conf/security/ to contain:

    type: kerberos

    2 Configure security filtering in the application

    This module uses Spring Security which operates using a Servlet filter which must be mapped in the web.xml file in src/main/webapp/WEB-INF:

    <!-- Spring Security -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring-security.xml</param-value>
    </context-param>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <filter>
        <filter-name>springSecurityFilterChain</filter-name>
        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>springSecurityFilterChain</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
<!-- Spring Security Ends -->

    This should be added as the first filter in the chain (at the top of the web.xml file). Remove any existing spring-security.xml file in the project because this configuration is pre-packaged by the Kerberos module.

    3 Configure the application for the Kerberos environment

    To use Kerberos with an application, a 'keytab' file is required. This identifies the application (service) and the host on which it is running in a special encrypted host key. You must configure a service principal and obtain a keytab file (usually done on the domain controller using Windows powershell) prior to configuring the Appkit application. After you have the service principal name and the keytab file configuration is easy. Add a file named kerberos.conf to src/main/resources/conf/security/ with these parameters:

    service-principal: HTTP/sharepoint-sp@sharepoint-dev.twigkit.com
keytab-location: classpath:sharepoint-dev.keytab
debug: true
# optional (defaults to '/WEB-INF/pages/login.jsp')
login-page: /WEB-INF/pages/login.jsp

    Set the service principal and keytab location accordingly. The debug parameter provides useful logging output from the Kerberos protocol interactions, and is recommended to be set to true for development. The login page is optional and provides a fallback page. If this is a standard Appkit login.jsp file, then the fallback form will be used to attempt login using form-based authentication (see Fallback strategy for more information). Alternatively this can direct to an 'unauthorized' error or debug page.

    4 Test the authentication

    Login to an account within the Kerberos 'realm' and navigate to the application in IE. The user should be silently authenticated.

    Further information on using the Kerberos provider

    Fallback strategy

    This module includes a default fallback strategy in the event Kerberos authentication fails. Reasons for failure can include:

    • Incorrect configuration of the application

    • An invalid keytab file

    • A browser that does not support Kerberos via the SPNEGO/Negotiate protocol

    • Unauthorized access

    • Access from outside the Kerberos 'realm'

    • The environment is not configured correctly for Kerberos (for example, some other authentication mechanism 'preferred')

    The fallback strategy is such that if Kerberos authentication fails a form is presented to attempt form based authentication. The page used is configurable as described above, and if forms based authentication is not supported it is recommended to point to a 'failure' or error page. In some scenarios it makes sense to have this fallback, depending on the nature of the security and environment in which the application is deployed. It should be noted that while a browser such as Internet Explorer supports NTLM, and often will attempt to fall back on this, this is not part of Kerberos and, due to restrictions in current Java runtimes, this is not supported.

    General troubleshooting

    First, check all of the above reasons the authentication can fail or 'fall back' from Kerberos. Use the debug configuration parameter and check the logs for information that could help to identify the cause. If it is a Windows environment it is recommended to check with the systems administrators that everything works correctly on the domain controller (check the Kerberos key distribution service, permissions of the service principal account, etc). You can view the headers passed from the browser in the debug information in the logs, these might provide an indication of why authentication failed (if Kerberos is used).

    If you find or suspect that NTLM is used, ensure you are trying to access the site using the host name configured in the SPN (service principal name). For example, if the SPN is HTTP/sharepoint-sp@sharepoint-dev.twigkit.com, you must use the URL for the host machine sharepoint-sp: either http://sharepoint-sp/ or http://sharepoint-sp.sharepoint-dev.twigkit.com/. Using 'localhost' or another alias will not work.

    Authentication works but the user is prompted for a username and password

    Usually in a Windows environment Kerberos allows silent authentication (single sign on via the account logged into the machine). In some cases the user is presented with a dialog (not an HTML form) the first time they visit the application or if the session expires, but when they enter their credentials it works fine. This can be a simple case that the user’s Windows credentials are not correctly configured or IE has 'integrated windows authentication' disabled. Make sure this is enabled in IE and that the credentials are saved correctly in the user account settings under the 'Control Panel'.

    How does this differ from Integrated Windows Authentication?

    Previously in Appkit, the only way to do silent 'integrated' authentication with Windows was using the Tomcat ISAPI connector, as described in our article about Integrated Windows Authentication.

    The Kerberos Security module simplifies the process for Kerberos enabled environments and keeps all of the configuration within the application.