Authentication exchange.

When a principal first accesses the network or attempts to access a secured service without a Ticket Granting Ticket, they are challenged to authenticate against the Authentication Service with their credentials. The AS validates the user’s provided credentials against the configured identity store, and upon successful authentication, the principal is issued a TGT which is cached by the client. The TGT also contains some session information so future communication between the client and KDC is secured.

Ticket granting, or authorization, exchange.

Once the principal has been issued a TGT, they may attempt to access secured services/resources. The principal sends a request to the Ticket Granting Service, passing the TGT it was issued by the KDC and requesting a Service Ticket for a specific destination. The TGS checks the TGT provided by the principal and verifies they have proper permissions to access the requested resource. If successful, the TGS issues an ST for the principal to access that specific destination. The TGS also creates session information for both the client as well as the destination server to allow for secure communication between the two. This session information is encrypted separately such that the client and server can only decrypt its own session information using long-term keys separately provided by the KDC to each, from previous transactions. The TGS then responds to the client with the ST which includes the session information for both the client and server.

Accessing the server.

Now that the principal has an ST for the secured service as well as a mechanism for secure communication to that server, client may now establish a connection and attempt to access the secured resource. Client starts by passing to the destination server the ST, which also contains the server component of the session information, it received from the TGS for that destination. The server attempts to decrypt the session information passed to it by the client using its long-term key from the KDC. If it succeeds, the client has been successfully authenticated to the server and the server is also considered authenticated to the client. At this point, trust has been established and secured communication between the client and server may proceed.

Configure the server identity, or host, security domain

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

If using the IBM JDK, the 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 Login Module Reference.

Configuring Web Application Security Domain

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, for example adding a <mapping> that manually maps users to roles, adding a second login module for mapping users to roles, and so on.

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

For a complete list of options for configuring the SPNEGO login module, refer to the Red Hat JBoss Enterprise Application Platform Login Module Reference.

Configure relevant system properties

JBoss EAP offers the ability to configure system properties related to connecting to Kerberos servers. Depending on the KDC, Kerberos Domain, and network configuration, the following 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 Red Hat JBoss Enterprise Application Platform Management CLI Guide.

Configure the web.xml to use the SPNEGO authentication method.

The web.xml file should contain the following:

Configure jboss-web.xml to use the configured security domain.

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

Add the JBoss Negotiation dependencies to the deployment.

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 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
Dependencies: org.jboss.security.negotiation

Clear existing service principal mappings.

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

Create a host user account.

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

Define the mapping between the USER_NAME and HOSTNAME.

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

Export the keytab of the user to the server on which JBoss EAP is installed.

Run the following command to export the keytab:

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

Define the principal within the security domain.

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

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