13.8. Configure Kerberos or Microsoft Active Directory Desktop SSO for Web Applications

Introduction

To authenticate your web or EJB applications using your organization's existing Kerberos-based authentication and authorization infrastructure, such as Microsoft Active Directory, you can use the JBoss Negotation capabilities built into JBoss EAP 6. If you configure your web application properly, a successful desktop or network login is sufficient to transparently authenticate against your web application, so no additional login prompt is required.

Difference from Previous Versions of the Platform

There are a few noticeable differences between JBoss EAP 6 and earlier versions:

  • Security domains are configured centrally, for each profile of a managed domain, or for each standalone server. They are not part of the deployment itself. The security domain a deployment should use is named in the deployment's jboss-web.xml or jboss-ejb3.xml file.
  • Security properties are configured as part of the security domain, as part of its central configuration. They are not part of the deployment.
  • You can no longer override the authenticators as part of your deployment. However, you can add a NegotiationAuthenticator valve to your jboss-web.xml descriptor to achieve the same effect. The valve still requires the <security-constraint> and <login-config> elements to be defined in the web.xml. These are used to decide which resources are secured. However, the chosen auth-method will be overridden by the NegotiationAuthenticator valve in the jboss-web.xml.
  • The CODE attributes in security domains now use a simple name instead of a fully-qualified class name. The following table shows the mappings between the classes used for JBoss Negotiation, and their classes.

Table 13.2. Login Module Codes and Class Names

Simple Name Class Name Purpose
Kerberos com.sun.security.auth.module.Krb5LoginModule Kerberos login module
SPNEGO org.jboss.security.negotiation.spnego.SPNEGOLoginModule The mechanism which enables your Web applications to authenticate to your Kerberos authentication server.
AdvancedLdap org.jboss.security.negotiation.AdvancedLdapLoginModule Used with LDAP servers other than Microsoft Active Directory.
AdvancedAdLdap org.jboss.security.negotiation.AdvancedADLoginModule Used with Microsoft Active Directory LDAP servers.
Jboss Negotiation Toolkit

The JBoss Negotiation Toolkit is a debugging tool which is available for download from https://community.jboss.org/servlet/JiveServlet/download/16876-2-34629/jboss-negotiation-toolkit.war. It is provided as an extra tool to help you to debug and test the authentication mechanisms before introducing your application into production. It is an unsupported tool, but is considered to be very helpful, as SPNEGO can be difficult to configure for web applications.

Procedure 13.1. Setup SSO Authentication for your Web or EJB Applications

  1. Configure one security domain to represent the identity of the server. Set system properties if necessary.

    The first security domain authenticates the container itself to the directory service. It needs to use a login module which accepts some type of static login mechanism, because a real user is not involved. This example uses a static principal and references a keytab file which contains the credential.
    The XML code is given here for clarity, but you should use the Management Console or Management CLI to configure your security domains.
    <security-domain name="host" cache-type="default">
       <authentication>
          <login-module code="Kerberos" flag="required">
             <module-option name="storeKey" value="true"/>
             <module-option name="useKeyTab" value="true"/>
             <module-option name="principal" value="host/testserver@MY_REALM"/>
             <module-option name="keyTab" value="/home/username/service.keytab"/>
             <module-option name="doNotPrompt" value="true"/>
             <module-option name="debug" value="false"/>
          </login-module>
       </authentication>
    </security-domain>		
    
    
  2. Configure a second security domain to secure the web application or applications. Set system properties if necessary.

    The second security domain is used to authenticate the individual user to the Kerberos or SPNEGO authentication server. You need at least one login module to authenticate the user, and another to search for the roles to apply to the user. The following XML code shows an example SPNEGO security domain. It includes an authorization module to map roles to individual users. You can also use a module which searches for the roles on the authentication server itself.
    <security-domain name="SPNEGO" cache-type="default">
       <authentication>
          <!-- Check the username and password -->
          <login-module code="SPNEGO"  flag="requisite">
             <module-option name="password-stacking" value="useFirstPass"/>
             <module-option name="serverSecurityDomain" value="host"/>
          </login-module>
          <!-- Search for roles -->
          <login-module code="UserRoles" flag="required">
             <module-option name="password-stacking" value="useFirstPass" />
             <module-option name="usersProperties" value="spnego-users.properties" />
             <module-option name="rolesProperties" value="spnego-roles.properties" />
          </login-module> 
       </authentication>
    </security-domain>		
    
    
  3. Specify the security-constraint and login-config in the web.xml

    The web.xml descriptor contain information about security constraints and login configuration. The following are example values for each.
    <security-constraint>
       <display-name>Security Constraint on Conversation</display-name>
       <web-resource-collection>
          <web-resource-name>examplesWebApp</web-resource-name>
          <url-pattern>/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
       <role-name>RequiredRole</role-name>
       </auth-constraint>
    </security-constraint>
    
    <login-config>
       <auth-method>SPNEGO</auth-method>
       <realm-name>SPNEGO</realm-name>
    </login-config>
     
    <security-role>
       <description> role required to log in to the Application</description>
       <role-name>RequiredRole</role-name>
    </security-role>		
    
    
  4. Specify the security domain and other settings in the jboss-web.xml descriptor.

    Specify the name of the client-side security domain (the second one in this example) in the jboss-web.xml descriptor of your deployment, to direct your application to use this security domain.
    You can no longer override authenticators directly. Instead, you can add the NegotiationAuthenticator as a valve to your jboss-web.xml descriptor, if you need to. The <jacc-star-role-allow> allows you to use the asterisk (*) character to match multiple role names, and is optional.
    <jboss-web>
       <security-domain>java:/jaas/SPNEGO</security-domain>
       <valve>
          <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name>
       </valve>
       <jacc-star-role-allow>true</jacc-star-role-allow>
    </jboss-web>		
    
    
  5. Add a dependency to your application's MANIFEST.MF, to locate the Negotiation classes.

    The web application needs a dependency on class org.jboss.security.negotiation to be added to the deployment's META-INF/MANIFEST.MF manifest, in order to locate the JBoss Negotiation classes. The following shows a properly-formatted entry.
    Manifest-Version: 1.0
    Build-Jdk: 1.6.0_24
    Dependencies: org.jboss.security.negotiation
    
Result

Your web application accepts and authenticates credentials against your Kerberos, Microsoft Active Directory, or other SPNEGO-compatible directory service. If the user runs the application from a system which is already logged into the directory service, and where the required roles are already applied to the user, the web application does not prompt for authentication, and SSO capabilities are achieved.