SPNEGOAuthnConfiguration

Current File(s): conf/authn/spnego-authn-config.xml, views/spnego-unavailable.vm, views/user-prefs.vm, conf/authn/authn.properties
Format: Properties, Native Spring

1 Overview
2 Enabling Module
3 Requirements
- 3.1 Kerberos Infrastructure
- 3.2 Browser Configuration
4 General Configuration
5 Kerberos System Configuration
6 Configuration of an Activation Condition
- 6.1 Example ActivationConditions in JavaScript:
- 6.2 Troubleshooting
7 Auto Login Management
8 SPNEGO User Interface
9 Attribute Resolution Implications
- 9.1 Configuring Subject Canonicalization
- 9.2 Adapting the Attribute Resolver Configuration
10 Testing the Availability of SPNEGO in the Browser
11 Reference

Overview

The authn/SPNEGO login flow supports SPNEGO-based Kerberos authentication, complying with RFC 4559, "SPNEGO-based Kerberos and NTLM HTTP Authentication" (http://tools.ietf.org/html/rfc4559). (Java only supports Kerberos, not the NTLM protocol.)

This mechanism allows the IdP to authenticate users by verifying a Kerberos service ticket sent by the client. Most current web browsers, including Internet Explorer, Firefox, Chrome, Opera, Safari and Konqueror, support SPNEGO/Kerberos based authentication. SPNEGO/Kerberos is most-often used in Microsoft Windows environments, and typically assumes the client machine is joined to a domain so that Kerberos credentials are obtained automatically. It can be tested, and given more technically-skilled users, used, without a domain-joined machine. It also works with MIT or Heimdal Kerberos, not just AD.

This login flow differs from the password-based Kerberos authentication provided by the Password login flow. Where the Password flow relies on the password submitted to the IdP, the SPNEGO login flow consumes a Kerberos ticket provided by the client, and the IdP never sees the password.

By default, this flow is configured without support for advanced authentication controls like passive or forced authentication, since this is generally not possible with SPNEGO authentication.

The SPNEGO login flow can be used via "opt-in" mode or "enforced" mode. In "opt-in" mode, users need to enable login via SPNEGO using an auto-login checkbox or button (see below). In "enforced" mode, SPNEGO is always tried (though possibly skipped in some cases based on an activation condition), independent of the auto-login option set by the users. By default, "opt-in" mode is used. The "enforced" mode is recommended only if you can ensure that Kerberos works in most situations for which any attached activation condition applies.

To use the authn/SPNEGO login flow, you need to configure Kerberos on your IdP server first. This includes the creation of a service principal in the Kerberos realm for your service, and usually includes obtaining a keytab file for that principal. A service password may also be used. See "Kerberos Infrastructure" below for more information.

General configuration of Kerberos is outside the scope of the IdP, and not described in detail here, but no native Kerberos libraries beyond Java’s implementation are required or used.

Enabling Module

Configuring and using this feature requires that you first enable the "idp.authn.SPNEGO" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.

(Windows)
C:\opt\shibboleth-idp> bin\module.bat -t idp.authn.SPNEGO || bin\module.bat -e idp.authn.SPNEGO
 
(Other)
$ bin/module.sh -t idp.authn.SPNEGO || bin/module.sh -e idp.authn.SPNEGO

Requirements

Kerberos Infrastructure

To use the authn/SPNEGO login flow, it is necessary to have the Kerberos environment configured and working properly.

Some interesting tutorials that may help are:

http://www.grolmsnet.de/kerbtut/

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

Before you start, please check that:

The service-principal (usually "HTTP/principal@your_realm.com") was configured at the KDC.
The keytab file holding the key of the service-principal was generated (using a keytab is recommended).
On the IdP server: Check if it is possible to get the service tickets from the KDC with the command kinit.

Browser Configuration

The clients' browsers need to be configured to support SPNEGO. See Single sign-on Browser configuration for details.

General Configuration

A few simple settings are controlled with conf/authn/authn.properties. The others, including the realms to use, are controlled with conf/authn/spnego-authn-config.xml.

The idp.authn.SPNEGO.enforceRun property controls the opt-in/enforcing mode (defaults to opt-in, false).

You need to configure the Kerberos service principal(s) you want to use in the shibboleth.authn.SPNEGO.Krb5.Realms bean. A usual configuration involves a single realm and service principal. If your environment contains multiple realms, you may need to configure more than one service principal. They will be tried in sequence when attempting to accept a ticket from the client.

Each value of the realms list bean must be a bean inherited from shibboleth.KerberosRealmSettings and identifies the service principal and keytab file or password to use. A keytab is recommended, but is a bit more work to obtain securely from your Kerberos administrator. Service principals used with SPNEGO MUST be of the form "HTTP/hostname", where "hostname" is the FQDN of the IdP service. This is required because the client will request a service ticket for that principal.

Example Realm Configuration

<util:list id="shibboleth.authn.SPNEGO.Krb5.Realms">

    <bean parent="shibboleth.KerberosRealmSettings"
        p:servicePrincipal="HTTP/idp.example.org@DOMAIN_A.COM"
        p:keytab="%{idp.home}/credentials/http_domainA.keytab" />

    <bean parent="shibboleth.KerberosRealmSettings"
        p:servicePrincipal="HTTP/idp.example.org@DOMAIN_B.COM"
        p:password="ihavennokeytab" />

</util:list>

Finally, note that a common deployment model is to enable the SPNEGO and the Password login flows together, requiring that both be enabled:

idp.authn.flows=SPNEGO|Password

Kerberos System Configuration

The actual Kerberos configuration is managed in a krb5.conf or krb5.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 the system property java.security.krb5.conf, as discussed here. If you want to set the system property java.security.krb5.conf, you should set it using the startup configuration of your Servlet container.

Configuration of an Activation Condition

There are known cases where the SPNEGO login process might break and stop in the browser, without returning to the IdP. As the IdP can't recover from this situation, the user can't continue the login process.

The following case is known:

Internet Explorer: If Internet Explorer gets a SPNEGO login request, but Kerberos is not available, Internet Explorer will fallback to the (deprecated) NTLM mechanism and show a login box to the user. No response will be sent to the IdP (unless the user actually enters credentials), and the user might get confused. (This case actually covers all Internet Explorer users who are not logged into a Windows Domain.)

The IdP provides a flexible mechanism to help avoid some of these situations, the use of an activation condition bean identified with the idp.authn.SPNEGO.activationCondition property.

The SPNEGO protocol itself doesn't provide any way for the IdP to reliably decide whether the browser supports a Kerberos login or not. You need to specify the conditions under which a Kerberos login will be available in your environment, typically based on the client's IP address or some text appearing in the user agent's identifier string. It's possible to implement such a condition in Java, but using a script is usually simpler.