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

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.

Example ActivationConditions in JavaScript:

The following examples assume that the condition property customObject is set to the bean shibboleth.HttpServletRequestSupplier.

// Default return value.
var activate = false;

// Check the client's IP address.
if (custom.get().getRemoteAddr().startsWith("192.168.42.")) {
    activate = true;
}

// Return the result.
activate;

// Default return value.
var activate = false;

// Check the user agent's identifier string.
var identifier = custom.get().getHeader("User-Agent");
if (identifier != null && identifier.match(/Kerberos/)) {
    activate = true;
}

// Return the result.
activate;

// This example assumes that the deployer uses the cookie "_idp_krb_enabled"
// to control the availability of SPNEGO. Any other cookie name could be
// used. (It has no relation with the cookie used for controlling "auto login".)
// If such a cookie is used, the view `views/user-prefs.vm` should be extended
// to allow the user to manage this setting. (By default, this view only
// supports to manage the auto-login setting.)

// Default return value.
var activate = false;

// Check whether the cookie "_idp_krb_enabled" is set.
var cookies = custom.get().getCookies();
if (cookies != null) {
    for (var i = 0; i < cookies.length; i++) {
        var cookie = cookies[i];
        if (cookie.getName() == "_idp_krb_enabled" && cookie.getValue != null && cookie.getValue() == "true") {
            activate = true;
        }
    }
}

// Return the result.
activate;

If a cookie based activation method is used, the view template `views/user-prefs.js` should be extended to allow the users to manage this option. Just add another option block:

Option in user-prefs.vm view to manage the cookie

          <div class="form-element-wrapper">
            <input type="checkbox" id="spnego-enable" name="_idp_krb_enabled" value="1" onClick="check(this)">
            #springMessageText("example.userprefs.spnego.enable", "Enable desktop login.")
          </div>

The following example shows a full-featured script including logging. To see the log lines in the IdP's log file, you need to configure a logger with name "shibboleth.authn.SPNEGO.ActivationCondition" and log level "DEBUG" in your log configuration file conf/logback.xml.

Full implementation, including logging

<bean id="shibboleth.SPNEGO.ActivationCondition" parent="shibboleth.Conditions.Scripted" factory-method="inlineScript"
		p:customObject-ref="shibboleth.HttpServletRequestSupplier">
    <constructor-arg>
        <value>
            <![CDATA[
                // This script activates SPNEGO if the client is part
                // of the network 192.168.42.0/24, the user agent's
                // identifier string contains the term "Kerberos",
                // or the cookie "_idp_krb_enabled" is set to "true".

                // Create logger object.
				var logger = Java.type("org.slf4j.LoggerFactory").getLogger("shibboleth.authn.SPNEGO.ActivationCondition");

                // Default return value.
                var activate = false;

                // Make HTTPServletRequest object known as "request".
                var request = custom.get();

                // Check the client's IP address.
                if (request.getRemoteAddr().startsWith("192.168.42.")) {
                    logger.debug("Activating SPNEGO for client in network 192.168.42.0/24.");
                    activate = true;
                }

                if (!activate) {
                    // Check the user agent's identifier string.
                    var identifier = request.getHeader("User-Agent");
                    if (identifier != null && identifier.match(/Kerberos/)) {
                        logger.debug("Activating SPNEGO for client with term 'Kerberos' in user agent's identifier string.");
                        activate = true;
                    }
                }

                if (!activate) {
                    // Check whether the cookie "_idp_krb_enabled" is set.
                    var cookies = request.getCookies();
                    if (cookies != null) {
                        for (var i = 0; i < cookies.length; i++) {
                            var cookie = cookies[i];
                            if (cookie.getName() == "_idp_krb_enabled" && cookie.getValue != null && cookie.getValue() == "true") {
                                logger.debug("Activating SPNEGO for client having cookie '_idp_krb_enabled' set to 'true'.");
                                activate = true;
                            }
                        }
                    }
                }

                // Return the result.
                activate;
            ]]>
        </value>
    </constructor-arg>
</bean>

The following code examples might be helpful for you to implement your script.

Useful / Help - Scripts

//
// Test the IP Range
//
var ipToLong = function(ip) {
    var components = ip.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
    if (components) {
        var iplong = 0;
        var power  = 1;
        for (var i = 4; i >= 1; i -= 1) {
            iplong += power * parseInt(components[i]);
            power *= 256;
        }
        return iplong;
    } else {
        return -1;
    }
};

ipOkFrom = ipToLong("10.208.0.0");
ipOkTo = ipToLong("10.239.255.255");
remIp = ipToLong("10.208.0.1");
if (remIp >= ipOkFrom && remIp <= ipOkTo) {
  activate = true;
} else {
  activate = false;
}

The following boilerplate code might be helpful for you to test your scripts outside of the IdP. (The script creates a mock custom object that can be used to test various functionality.)

Boilerplate code to test a script

//
// Use this boilerplate code if you want to test your script standalone (i.e. outside of the IdP).
// For testing, you can use a service like https://jsfiddle.net for example.
//

my_cookie1 = new Object();
my_cookie1.getName = function() { return "my_cookie_name"};
my_cookie1.getValue = function() { return "my_cookie_value"};

function Custom() {
    // Define the client's IP address
    this.remoteAddr = "127.0.10.10";
    
    // Define the client's user agent identifier string
    this.getHeader = function(header_str) {
      my_header = {"User-Agent":"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101 Firefox/38.0",} 
      return my_header[header_str];
    }

    // Define a cookie to be returned
    this.getCookies = function() {
      return [my_cookie1];
    }
}

var custom = new Custom();

// Examples
alert("my IP = " + custom.remoteAddr);
alert("my cookie = " + custom.getCookies()[0].getValue());
alert("my browser = " + custom.getHeader("User-Agent"));

Troubleshooting

While implementing your activation condition, you may encounter the following problems:

• The IdP doesn't start because of a syntax error in the JavaScript code. You should find a javax.script.ScriptException exception telling you more about the problem in one of the logs available.

• The script produces a runtime error while it is executed. In this case, you will find an error message in the IdP's log telling more about the error. The log line will look similar to this:
  2015-11-13 11:44:13,408 - ERROR [net.shibboleth.idp.profile.logic.ScriptedPredicate:119] - Anonymous Scripted Predicate : Error while executing Predicate script
  <Exception>

• The script runs successfully, but evaluates to false. This means that the authn/SPNEGO flow won't be available. If you added logging to your script and adapted your logging configuration accordingly, as described above, you will find appropriate log messages in the IdP's log.

Auto Login Management

Users can enable or disable the auto-login cookie by visiting a URL at the path "/idp/profile/user/prefs". You can customize the page displayed by modifying the view template in views/user-prefs.vm.

SPNEGO User Interface

The SPNEGO authentication process isn't visible to the user. The communication takes place between the IdP and the browser, without requiring user intervention. If an error occurs, an error page is shown to the user explaining the problem and allowing to return control to the IdP to continue. The default implementation of the view rendering this page uses JavaScript to automatically return to the IdP so that the user doesn't need to do anything.

If Internet Explorer is used and Kerberos is not available, and no activation condition (see above) is configured or doesn't prevent this from happening, the browser may show a login dialog box to the user instead of an error page. Users may be confused and may not be able to recover from this situation, so this case should be avoided by configuring an appropriate activation condition if possible.

The view rendering the error page is named views/spnego-unavailable.vm and can be adapted to your needs.

Attribute Resolution Implications

As the SPNEGO authentication doesn't result in a simple username (e.g. "jdoe") but in a Kerberos Principal name that includes the Kerberos realm (e.g. "jdoe@EXAMPLE.ORG"), your current configuration of the attribute resolution might not work, because it expects a simple username to look up the user in the user directory.

You basically have two options to extend your configuration:

• Configure subject c14n to transform the Kerberos Principal name into a simple username. This method works if the username that is contained in the Kerberos Principal name more or less identical to the username you want to normalize to. Then, you don't need to adapt the existing attribute resolution configuration.

• Adapt the configuration of the attribute resolution to additionally support Kerberos Principal names besides simple usernames. Choose this approach if the subject canonicalization doesn't lead to unique usernames (e.g. because you have multiple realms and the usernames are not unique over all realms; or because this canonicalization may affect e-mail addresses used as usernames, too).

The following two subsections describe both approaches.

Configuring Subject Canonicalization

This approach requires that each Kerberos Principal name can be transformed to a unique simple username.

You can configure a transformation in the file conf/c14n/simple-subject-c14n-config.xml. See that feature's documentation for further information about the available options.

For example, the following transformation rule removes the realm "@EXAMPLE.ORG":

subject-c14n-config.xml example removing the realm @EXAMPLE.ORG

...
    <!-- Apply any regular expression replacement pairs after authentication. -->
    <util:list id="shibboleth.c14n.simple.Transforms">
        <bean parent="shibboleth.Pair" p:first="^(.+)@EXAMPLE\.ORG$" p:second="$1" />
    </util:list>
...

Note: In case you allow your users to use the e-mail address for username/password login, this rule may also apply to such an e-mail address in case the user entered the address in upper case. If this may affect you, please have a look at the next approach.

Adapting the Attribute Resolver Configuration

In this approach, the username is kept as is, but the attribute resolver defines additional attributes from the Kerberos Principal name that can be used in the user directory lookup filter template.

The following example defines the attributes krbPrincipalname and krbDomain that are used in the user directory lookup filter template:

Extract the username and realm from the Kerberos Principal name

    <!-- The principal name resulting from the authentication. -->
    <AttributeDefinition id="principalName"
                         xsi:type="PrincipalName"
                         dependencyOnly="true">
    </AttributeDefinition>
 
    <!-- Extract the simple username from the Kerberos Principal name. -->
    <AttributeDefinition id="krbPrincipalname"
                         xsi:type="Mapped"
                         dependencyOnly="true">
        <InputAttributeDefinition ref="principalName" />
 
        <DefaultValue passThru="true"/>
        <ValueMap>
            <ReturnValue>$1</ReturnValue>
            <SourceValue>(.+)@EXAMPLE.ORG</SourceValue>
        </ValueMap>
    </AttributeDefinition>
 
    <!-- Map the Kerberos realm to a domain name. -->
    <AttributeDefinition id="krbDomain"
                         xsi:type="Mapped"
                         dependencyOnly="true">
        <InputAttributeDefinition ref="principalName" />

        <DefaultValue passThru="true"/>
        <ValueMap>
            <ReturnValue>domain_a.com</ReturnValue>
            <SourceValue>(.+)@DOMAIN_A.COM</SourceValue>
        </ValueMap>
        <ValueMap>
            <ReturnValue>domain_b.com</ReturnValue>
            <SourceValue>(.+)@DOMAIN_B.COM</SourceValue>
        </ValueMap>
    </AttributeDefinition>

Then, the user directory lookup filter template needs to be adapted to use the attributes defined above:

Example LDAP DataConnector

    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ...>
        
        <InputAttributeDefinition ref="krbPrincipalname" />
        <InputAttributeDefinition ref="krbDomain" />
        <FilterTemplate>
            <![CDATA[
                (&(|(sAMAccountName=$resolutionContext.principal)(mail=$resolutionContext.principal)(&(sAMAccountName=$krbPrincipalname.get(0))(msSFU30NisDomain=$krbDomain.get(0))))(objectClass=user))
            ]]>
        </FilterTemplate>

        ...
    </DataConnector>

See the documentation for a detailed description of attribute resolution configuration.

Testing the Availability of SPNEGO in the Browser

If you extend the Password login flow to include SPNEGO as an alternative login method, you may further optimize the password login page to show the SPNEGO login only if it's really available in the browser by using AJAX technology. Although this is fully optional, it may lead to a better user experience.

This section doesn't explain in detail how to do this. The real implementation is left to you as part of the customization of the login page template. But we provide an example of a JSP script that checks whether the browser is capable of providing a Kerberos ticket.

You need to install this script to edit-webapp/spnego-test.jsp and rebuild the WAR file and restart the application container to make it available. This example script initiates a SPNEGO login and returns a status in JSON. You can adapt this scripts to your needs.

JSP script to check whether SPNEGO works

<%@ page trimDirectiveWhitespaces="true" %>
<%@ page import="org.apache.commons.codec.binary.Base64" %>
<%@ page import="java.util.Arrays" %>
<%@ page contentType="application/json; charset=UTF-8" %>
<%
String status = "";
final String authorizationHeader = request.getHeader("Authorization");
if (authorizationHeader == null || !authorizationHeader.startsWith("Negotiate ")) {
    status = "SPNEGONotAvailable";
    response.addHeader("WWW-Authenticate", "Negotiate");
    response.setStatus(401);
} else {
    // Test for NTLM mechanism request.
    final byte[] headerNTLM = {(byte) 0x4E, (byte) 0x54, (byte) 0x4C, (byte) 0x4D, (byte) 0x53, (byte) 0x53, (byte) 0x50};
    final byte[] gssapiData = Base64.decodeBase64(authorizationHeader.substring(10).getBytes());
    if (Arrays.equals(headerNTLM, Arrays.copyOfRange(gssapiData, 0, 7))) {
        // GSS-API data represents an NTLM mechanism request.
        status = "NTLMUnsupported";
    } else {
        // Assume GSS-API data represents an SPNEGO mechanism request.
        status = "SPNEGOAvailable";
    }
    response.setStatus(200);
}
%>
{
    "status": "<%= status %>"
}

The login page can send an AJAX query to the URL path /idp/spnego-test.jsp and then evaluate the result:

AJAX example to detect SPENGO using JSP above

    ## SPNEGO detection, button fixup
    <script>
        $( document ).ready(function() {
            // query server and test if browser is ready to support SPNEGO
            $.ajax({
                url: "/idp/spnego-test.jsp",
                type: "GET",
                dataType: "json",
            })
            .done(function( json ) {
                var status = json["status"];
                if (status == "SPNEGOAvailable" ) {
                    // display the SPNEGO functionality to the user
                    $('button[name="_eventId_authn/SPNEGO"]').text('Login with SPNEGO');
                    $('button[name="_eventId_authn/SPNEGO"]').css("display", "inline");
                }
            });
        });
    </script>

Note: This example is not part of the main IdP distribution and is provided without warranty.

Reference

<list>
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos" />
    <bean parent="shibboleth.SAML1AuthenticationMethod"
        c:method="urn:ietf:rfc:1510" />
</list>

idp.authn.SPNEGO.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos, \
    saml1/urn:ietf:rfc:1510

<util:list id="shibboleth.AvailableAuthenticationFlows">
 
    <bean p:id="authn/SPNEGO" parent="shibboleth.AuthenticationFlow"
            p:order="%{idp.authn.SPNEGO.order:1000}"
            p:nonBrowserSupported="%{idp.authn.SPNEGO.nonBrowserSupported:false}"
            p:passiveAuthenticationSupported="%{idp.authn.SPNEGO.passiveAuthenticationSupported:false}"
            p:forcedAuthenticationSupported="%{idp.authn.SPNEGO.forcedAuthenticationSupported:false}"
            p:proxyRestrictionsEnforced="%{idp.authn.SPNEGO.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
            p:proxyScopingEnforced="%{idp.authn.SPNEGO.proxyScopingEnforced:false}"
            p:discoveryRequired="%{idp.authn.SPNEGO.discoveryRequired:false}"
            p:lifetime="%{idp.authn.SPNEGO.lifetime:%{idp.authn.defaultLifetime:PT1H}}"
            p:inactivityTimeout="%{idp.authn.SPNEGO.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}"
            p:reuseCondition-ref="#{'%{idp.authn.SPNEGO.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:activationCondition-ref="#{'%{idp.authn.SPNEGO.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:subjectDecorator-ref="#{getObject('%{idp.authn.SPNEGO.subjectDecorator:}'.trim())}">
        <property name="supportedPrincipalsByString">
            <bean parent="shibboleth.CommaDelimStringArray"
                c:_0="#{'%{idp.authn.SPNEGO.supportedPrincipals:}'.trim()}" />
        </property>
    </bean>
 
</util:list>