The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
KerberosAuthnConfiguration
This topic is about the use of Kerberos strictly on the IdP server. If you're looking for the end-to-end use of Kerberos with a web browser using the SPNEGO GSS-API mechanism (often referred to as desktop authentication), see the SPNEGOAuthnConfiguration topic.
Current File(s): conf/authn/password-authn-config.xml, conf/authn/krb5-authn-config.xml (V4.0), conf/authn/authn.properties (V4.1+)
Format: Native Spring, Properties, Kerberos
Overview
This CredentialValidator back-end for the password authentication login flow uses the Kerberos library built into Java for password-based authentication instead of using the JAAS module that traditionally wraps those calls.
The primary advantage of this approach is the capability to prevent a rogue KDC from spoofing responses by validating its knowledge of a service principal key configured locally in a keytab file, which is a standard practice for safe use of Kerberos in server-side scenarios. It is STRONGLY urged that this feature be used when possible.
General Configuration
If desired, it's possible to directly configure the various settings within the validator bean instead of or in addition to relying on the defaults. Refer to the KerberosCredentialValidator javadoc for a complete summary, along with the example below.
Kerberos Configuration
The actual Kerberos library configuration is managed in a conf or ini file that can be placed in a number of different locations. On non-Windows servers, using a system-wide configuration in /etc/krb5.conf is generally advised. It's possible to have Java-specific configurations and/or provide the path to a configuration using a system property. Refer to the Java documentation for details.
It is of critical concern that you consider the impact of foreign realm usage. Operating the Java Kerberos client in its default configuration without including a service principal is inherently dangerous because Java defaults to locating foreign realm KDCs via DNS. Therefore you MUST do one of the following to prevent inadvertent access by principals in realms other than your own:
Set dns_lookup_kdc = false in the [libdefaults] section of the Kerberos configuration file.
Supply a service principal and keytab to ensure that the IdP shares a key with the KDC that responds to it.
It is also possible to implement rules within the IdP controlling the permissible usernames, but these are workarounds at best and one of the above is more strongly recommended.
Examples
Chaining Validators
One complication of chaining Kerberos KDCs together is that the overall realm configuration is global to Java, so you can't just have separate krb5.conf files in each case. That means you have to manipulate the user's input to ensure that the values will be explicitly realm-qualified.
Under the assumption that principal names in the two realms are unique (without which, things get much more complex and dangerous obviously), something like this would allow chaining of the two. The example considers two realms, "FOO.EXAMPLE.ORG" and "BAR.EXAMPLE.ORG", and the transforms applied strip the username if it's entered in the form of an email address before appending the realm.
Reference