Chapter 2. How to Setup SSO for Red Hat JBoss Enterprise Application Platform 6 with Kerberos

This security domain authenticates the container itself to the KDC. It needs to use a login module which accepts a static login mechanism since a real user is not involved in this connection. The below example uses a static principal and references a keytab file which contains the credential.

/subsystem=security/security-domain=host:add(cache-type=default)

/subsystem=security/security-domain=host/authentication=classic:add

/subsystem=security/security-domain=host/authentication=classic/login-module=Kerberos:add( \
  code=Kerberos, \
  flag=required, \
  module-options=[ \
    ("storeKey"=>"true"), \
    ("refreshKrb5Config"=>"true"), \
    ("useKeyTab"=>"true"), \
    ("principal"=>"host/testserver@MY_REALM"), \
    ("keyTab"=>"/home/username/service.keytab"), \
    ("doNotPrompt"=>"true"), \
    ("debug"=>"false") \
  ])

reload

<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>

If using the IBM JDK, options for Kerberos module are different. The jboss.security.disable.secdomain.option system property must be set to true (see Configure Relevant System Properties). In addition the login module should be updated to the following:

<security-domain name="host" cache-type="default">
  <authentication>
    <login-module code="Kerberos" flag="required">
      <module-option name="principal" value="HTTP/testserver@MY_REALM"/>
      <module-option name="credsType" value="acceptor"/>
      <module-option name="useKeytab" value="file:///root/keytab"/>
    </login-module>
  </authentication>
</security-domain>

For a complete list of options for configuring the Kerberos login module, refer to the Red Hat JBoss Enterprise Application Platform 6 Security Guide.

The web application security domain is used to authenticate the individual user to the KDC. There needs to be at least one login module to authenticate the user, and a way to search for the roles to apply to the user. The latter can be accomplished in many different ways (e.g. adding a <mapping> that manually maps users to roles, adding a second login module for mapping users to roles, etc).

The following shows an example web application security domain.

/subsystem=security/security-domain=app-spnego:add(cache-type=default)

/subsystem=security/security-domain=app-spnego/authentication=classic:add

/subsystem=security/security-domain=app-spnego/authentication=classic/login-module=SPNEGO:add( \
  code=SPNEGO, \
  flag=required, \
  module-options=[ \
    ("serverSecurityDomain"=>"host") \
  ])

reload

<security-domain name="app-spnego" cache-type="default">
  <authentication>
    <!-- Check the username and password -->
    <login-module code="SPNEGO"  flag="required">
      <module-option name="serverSecurityDomain" value="host"/>
    </login-module>
    <!-- Second login module to search for roles -->
  </authentication>
  <!-- Alternatively, a 'mapping' element may be added instead of a second login module to map users to roles-->
</security-domain>

For a complete list of options for configuring the SPNEGO login module, refer to the Red Hat JBoss Enterprise Application Platform 6 Security Guide.

JBoss EAP 6 offers the ability to configure system properties related to connecting to Kerberos servers. Depending on the KDC, Kerberos Domain, and network configuration, the below system properties may or may not be required.

<system-properties>
  <property name="java.security.krb5.kdc" value="mykdc.mydomain"/>
  <property name="java.security.krb5.realm" value="MY_REALM"/>
  <property name="java.security.krb5.conf" value="/path/to/krb5.conf"/>
  <property name="jboss.security.disable.secdomain.option" value="true"/>
  <property name="sun.security.krb5.debug" value="false"/>
</system-properties>

For more information about configuring system properties, refer to the Configure System Properties Using the Management CLI section of the Red Hat JBoss Enterprise Application Platform 6 Administration and Configuration Guide.

The web.xml file should contain the following:

The <security-constraint> and <security-role> elements enable administrators to setup restricted or unrestricted areas based on URL patterns and roles. This allows resources to be secured or unsecured.

<web-app>
  <display-name>App1</display-name>
  <description>App1</description>
  <!-- Define a security constraint that requires the All role to access resources -->
  <security-constraint>
    <display-name>Security Constraint on Conversation</display-name>
    <web-resource-collection>
      <web-resource-name>exampleWebApp</web-resource-name>
      <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>All</role-name>
    </auth-constraint>
  </security-constraint>
<!-- Define the Login Configuration for this Application -->
  <login-config>
    <auth-method>SPNEGO</auth-method>
    <realm-name>SPNEGO</realm-name>
  </login-config>
<!-- Security roles referenced by this web application -->
  <security-role>
    <description>Role required to log in to the Application</description>
    <role-name>All</role-name>
  </security-role>
</web-app>

The jboss-web.xml file should have the following:

<jboss-web>
  <security-domain>app-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>

A web application using SPNEGO and JBoss Negotiation requires a dependency to be defined in jboss-deployment-structure.xml so that the JBoss Negotiation classes can be located. Since JBoss EAP 6 provides all necessary JBoss Negotiation and related classes, the application just needs to declare them as dependencies to use them.

<jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="org.jboss.security.negotiation"/>
    </dependencies>
  </deployment>
</jboss-deployment-structure>

Alternatively, this dependency may be defined in a META-INF/MANIFEST.MF file instead:

Manifest-Version: 1.0
Build-Jdk: 1.6.0_24
Dependencies: org.jboss.security.negotiation

On a Microsoft Windows network some mappings are created automatically. Delete the automatically created mappings to map the identity of the server to the service principal for negotiation to take place correctly. The mapping enables the web browser on the client computer to trust the server and attempt SPNEGO. The client computer verifies with the domain controller for a mapping in the form of HTTP/HOSTNAME.

The following are the steps to delete the existing mappings:

setspn -L MACHINE_NAME

setspn -D HTTP/HOST_NAME MACHINE_NAME

setspn -D host/HOSTNAME MACHINE_NAME

In the rest of the section the host user name is referred to as USER_NAME.

Run the following command to configure the Service Principal Mapping:

ktpass -princ HTTP/HOSTNAME@REALM -pass * -mapuser DOMAIN\USER_NAME

Enter the password for the user name when prompted.

Verify the mapping by running the following command, setspn -L USER_NAME

Run the following command to export the keytab:

ktab -k service.keytab -a HTTP/HOSTNAME@REALM

The principal can be defined or updated in the security domain as follows:

<module-option name="principal">HTTP/HOSTNAME@REALM</module-option>