The Kerberos Idp Handler uses the kerberos protocol to implement an SSO (Single Sing On) authentication mechanism.

A presentation with some general information about the project can be found on the SWITCH website


Kerberos Infrastructure

To use the "Kerberos Login Handler" in the Identity Provider, first is necessary to have the kerberos environment configured and working properly.

Some interesting tutorials are:

HTTP-Based Cross-Platform Authentication by Using the Negotiate Protocol.

Before start please check if:

There is also a step by step guide to setting up kerberos at    The hardest area in getting shibboleth setup with kerberos "true single sign on" is the kerberos setup. It is therefore recommended that you get kerberos to work on it's own on the IdP  server before you try integrating with shibboleth.   This guide walks you through these steps, once you have kerberos setup and working on it's own integration with shibboleth is relatively straight forward.     The guide details setup of mod_auth_kerb  which is the simplest route to proving you have SPNEGO based "true single sign on" working .  Once that is setup the Kerberos login handler detailed in this wiki page  is a better solution for providing a user facing service as it's behavior when dealing with clients that don't have a kerberos ticket (mobile phones etc)   is superior in that it presents a "web form" based login rather than the grey pop up "basic auth" login box.    

Installation and configuration    

svn export java-idp-kerberos-login-handler
cd java-idp-kerberos-login-handler
mvn package

IdP - Configuration

Copy the example pages from the source (/examples) to the installation folder at: $IDP_INSTALL_DIR/src/main/webapp/

Rename the distribution files:

mv kerberos-default.jsp.dist kerberos-default.jsp
mv kerberos.css.dist kerberos.css

And check the configurations at kerberos-default.jsp. In this file you can change the text messages, enable or disable some functionality (kerberos enabled, visible and auto-login) and customize functions.

Copy the .jar file to the installation folder:

cp target/kerberos-login-handler-X.0.jar $IDP_INSTALL_DIR/lib

To expose the Kerberos Login Handler to the user you have two options. Either you include a snippet into your existing UsernamePassword Login Handler or you can use just the Kerberos Login Handler.

1 - Kerberos embedded with UsernamePassword login page


<jsp:include page="" />


2 - "Kerberos only" login page

Configuring the server (tomcat)

In the web-application you have to enable the Kerberos login servlets. You do that in $IDP_INSTALL_DIR/src/main/webapp/WEB-INF/web.xml:


    <!-- Kerberos Login Handler -->





Kerberos - Test Page

There is a Servlet to test if the browser supports kerberos. This configuration is necessary if showTestPage=true at kerberos-default.jsp (default=false).
- The "kerberos-report.jsp" file must to be in the "$IDP_INSTALL_DIR/src/main/webapp/" folder
- Configure the servlet at $IDP_INSTALL_DIR/src/main/webapp/WEB-INF/web.xml:

    <!-- Test Kerberos -->


handler.xml configuration

Configure the handler.xml at:

<ProfileHandlerGroup xmlns=
        urn:mace:shibboleth:2.0:idp:profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
(...) classpath:/schema/kerberos-login-handler.xsd
    <!-- Kerberos Idp -->
    <ph:LoginHandler xsi:type="krb:KERBEROS"
<!-- LoginHandler optional attributes:
                  kerberosCfg - kerberos configuration file (e.g.: /etc/krb.conf)
                  customUnauthorized - custom html page for error 401 - Unauthorized. (e.g.:  /opt/shibboleth-identityprovider-2.2.1/src/main/webapp/error-404.jsp)
                  auto_login_durantion - auto login duration (seconds)
                  loginPagePattern - (default: "/login.jsp") - path for login page
                  krbServletPattern - (default: "/Authn/Kerberos") - path for kerberos login page
        <krb:Realm domain="DOMAIN_A.COM">

        <krb:Realm domain="DOMAIN_B.COM">
<!-- Realm optional elements:
            <krb:password>password (if no keytab available)</krb:password>


Attribute resolver configuration

Configure the attribute-resolver.xml at:

Check if your configuration will accept the "principal name" provided by Kerberos (format: Principal@REALM.COM).

Here you can find an example.

Log configuration

The logging for the Handler is configured in the logging.xml file. It can be found at:


<!-- Log level for Kerberos - LoginHandler -->
<logger name="ch.SWITCH.aai.idp.kerberos">
<level value="DEBUG"/>



Backup the IdP configuration before re-deploying the application:


Configuration - Client Side

The client's browser must to be configured before using Kerberos - Single Sign on. See the Documentation


Contact for comments/questions:

Rodrigo Ristow -

University of Applied Sciences and Arts Northwestern Switzerland (FHNW)