The Shibboleth IdP V3 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP4 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/krb5-authn-config.xml
Format: Native Spring
V2 Legacy File(s): conf/handler.xml, conf/login.config
Overview
This back-end for the password authentication login flow uses the Oracle Java implementation's Kerberos library for password-based authentication instead of using a JAAS module.
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. It is STRONGLY urged that this feature be used.
General Configuration
Configuring Kerberos as a back-end requires that the right import is active in authn/password-authn-config.xml:
<import resource="krb5-authn-config.xml" />
The other imports must be commented or removed.
A few beans are defined in authn/krb5-authn-config.xml to configure this back-end by setting some Kerberos-related options.
A bean alias is also defined that instantiates the Kerberos back-end action as the "ValidateUsernamePassword" step of the web flow. This must not be changed.
Kerberos Configuration
The actual Kerberos 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, as discussed here.
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.
Reference
Beans
The beans defined in authn/krb5-authn-config.xml follow:
Bean ID | Type | Default | Function |
|---|---|---|---|
| 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 3.2 | 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 3.2 | Path | Path to a keytab file containing keys belonging to the service principal defined above |
Notes
TBD