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

1 Overview
2 General Configuration
3 Kerberos Configuration
4 Examples
- 4.1 Chaining Validators
5 Reference

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

Configuring Kerberos as a back-end in the simplest fashion relies on beans defined via an import in authn/password-authn-config.xml:

Import in authn/password-authn-config.xml

<import resource="krb5-authn-config.xml" />

A few beans are defined in this file to globally configure this back-end by setting some Kerberos-related options. With V4, these beans are chiefly used for backward compatibility, and as default settings that can be overridden on specific instances of beans inheriting from shibboleth.KerberosValidator defined in authn/password-authn-config.xml in the shibboleth.authn.Password.Validators bean.

In the simple case of a single back-end:

Defining use of Kerberos in password-authn-config.xml

<util:list id="shibboleth.authn.Password.Validators">
	<!-- Default bean uses the settings defined in krb5-authn-config.xml -->
    <ref bean="shibboleth.KerberosValidator" />
</util:list>

Configuring Kerberos as a back-end relies on beans internally that are configured using authn/authn.properties along with the OS-supplied Kerberos configuration.

Older releases included an authn/krb5-authn-config.xml file; this remains supported but is no longer required or provided.

Adding additional beans may be needed in very advanced cases where a higher degree of control is required, and you are welcome to place them within authn/password-authn-config.xml.

In the simple case of a single back-end:

Defining use of Kerberos in password-authn-config.xml

<util:list id="shibboleth.authn.Password.Validators">
	<!-- Default bean uses the settings defined in authn/authn.properties -->
    <ref bean="shibboleth.KerberosValidator" />
</util:list>

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

The beans defined in authn/krb5-authn-config.xml follow. These are defaults that can be overridden per-validator in whole or in part.

Bean ID	Type	Default	Description

Bean ID	Type	Default	Description
shibboleth.authn.Krb5.RefreshConfig	Boolean	False	Whether to reload the underlying Kerberos configuration (generally in /etc/krb5.conf) on every login attempt
shibboleth.authn.Krb5.PreserveTicket	Boolean	False	Whether to preserve the resulting Kerberos TGT in the Java Subject's private credential set
shibboleth.authn.Krb5.ServicePrincipal	String		Name of a service principal to use to verify the KDC supplying the TGT, by requesting and verifying a service ticket issued for it
shibboleth.authn.Krb5.Keytab	Path		Path to a keytab file containing keys belonging to the service principal defined above

The following properties are usable in authn/authn.properties to control Kerberos use. These are defaults that can be overridden per-validator in whole or in part.

Name	Default	Description

Name	Default	Description
idp.authn.Krb5.refreshConfig	false	Whether to reload the underlying Kerberos configuration (generally in /etc/krb5.conf) on every login attempt
idp.authn.Krb5.preserveTicket	false	Whether to preserve the resulting Kerberos TGT in the Java Subject's private credential set
idp.authn.Krb5.servicePrincipal		Name of a service principal to use to verify the KDC supplying the TGT, by requesting and verifying a service ticket issued for it
idp.authn.Krb5.keytab		Path to a keytab file containing keys belonging to the service principal defined above