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
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://www.grolmsnet.de/kerbtut/
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 http://research.ncl.ac.uk/gfivo/documents/UsingKerberosticketsfortrueSingleSignOn.pdf 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.
svn export https://subversion.switch.ch/svn/general/aai/java-idp-kerberos-login-handler/tags/X.0 java-idp-kerberos-login-handler cd java-idp-kerberos-login-handler mvn package |
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.
(...) </form> <jsp:include page="kerberos-login.inc.jsp" /> (...) |
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:
<webapp>
(...)
<!-- Kerberos Login Handler -->
<servlet>
<servlet-name>KrbLoginServlet</servlet-name>
<servlet-class>ch.SWITCH.aai.idp.kerberos.KrbLoginServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>KrbLoginServlet</servlet-name>
<url-pattern>/Authn/Kerberos/Login</url-pattern>
</servlet-mapping>
(...)
</webapp>
|
Attention!
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 -->
<servlet>
<servlet-name>TestKrbServlet</servlet-name>
<servlet-class>ch.SWITCH.aai.idp.kerberos.test.TestKrbServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>TestKrbServlet</servlet-name>
<url-pattern>/Authn/Kerberos/test-kerberos</url-pattern>
</servlet-mapping>
(...)
|
Configure the handler.xml at:
<ProfileHandlerGroup xmlns=
"urn:mace:shibboleth:2.0:idp:profile-handler"
(...)
xmlns:krb="http://www.switch.ch/aai/idp/kerberos"
xsi:schemaLocation="
urn:mace:shibboleth:2.0:idp:profile-handler classpath:/schema/shibboleth-2.0-idp-profile-handler.xsd
(...)
http://www.switch.ch/aai/idp/kerberos classpath:/schema/kerberos-login-handler.xsd
">
(...)
<!-- Kerberos Idp -->
<ph:LoginHandler xsi:type="krb:KERBEROS"
kerberosCfg="/opt/kerberos/krb5.conf"
customUnauthorized="/opt/shibboleth-identityprovider-2.2.0/src/main/webapp/unauthorized.html"
>
<!-- 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
-->
<ph:AuthenticationMethod>urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos</ph:AuthenticationMethod>
<krb:Realm domain="DOMAIN_A.COM">
<krb:principal>HTTP/aai-logon.domain_a.com@DOMAIN_A.COM</krb:principal>
<krb:keytab>/opt/kerberos/http_domainA.keytab</krb:keytab>
</krb:Realm>
<krb:Realm domain="DOMAIN_B.COM">
<krb:principal>HTTP/aai-logon.domain_b.com@DOMAIN_B.COM</krb:principal>
<krb:keytab>/opt/kerberos/http_domainB.keytab</krb:keytab>
<!-- Realm optional elements:
<krb:password>password (if no keytab available)</krb:password>
-->
</krb:Realm>
</ph:LoginHandler>
(...)
</ProfileHandlerGroup>
|
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.
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"/> </logger> (...) |
Backup the IdP configuration before re-deploying the application:
$IDP_INSTALL_DIR/install.sh |
The client's browser must to be configured before using Kerberos - Single Sign on. See the Documentation
Contact for comments/questions:
Rodrigo Ristow - rodrigo.ristow@fhnw.ch
University of Applied Sciences and Arts Northwestern Switzerland (FHNW)