Chapter 2. How to Set Up SSO for JBoss EAP with Kerberos

Configure a kerberos-security-factory.

/subsystem=elytron/kerberos-security-factory=krbSF:add(principal="HTTP/host@REALM", path="/path/to/http.keytab", mechanism-oids=[1.2.840.113554.1.2.2, 1.3.6.1.5.5.2])

Configure the system properties for Kerberos.

Depending on how your environment is configured, you will need to set some of the system properties below.

To configure a system property in JBoss EAP using the management CLI:

/system-property=java.security.krb5.conf:add(value="/path/to/krb5.conf")

Configure an Elytron security realm for assigning roles.

The client’s Kerberos token will provide the principal, but you need a way to map that principal to a role for your application. There are several ways to accomplish this, but this example creates a filesystem-realm, adds a user to the realm that matches the principal from the Kerberos token, and assigns roles to that user.

/subsystem=elytron/filesystem-realm=exampleFsRealm:add(path=fs-realm-users, relative-to=jboss.server.config.dir)

/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity(identity=user1@REALM)

/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity-attribute(identity=user1@REALM, name=Roles, value=["Admin","Guest"])

Add a simple-role-decoder.

/subsystem=elytron/simple-role-decoder=from-roles-attribute:add(attribute=Roles)

This simple-role-decoder decodes a principal’s roles from the Roles attribute. You can change this value if your roles are in a different attribute.

Configure a security-domain.

/subsystem=elytron/security-domain=exampleFsSD:add(realms=[{realm=exampleFsRealm, role-decoder=from-roles-attribute}], default-realm=exampleFsRealm, permission-mapper=default-permission-mapper)

Configure an http-authentication-factory that uses the kerberos-security-factory.

/subsystem=elytron/http-authentication-factory=example-krb-http-auth:add(http-server-mechanism-factory=global, security-domain=exampleFsSD, mechanism-configurations=[{mechanism-name=SPNEGO, mechanism-realm-configurations=[{realm-name=exampleFsSD}], credential-security-factory=krbSF}])

Configure an application-security-domain in the undertow subsystem:

/subsystem=undertow/application-security-domain=app-spnego:add(http-authentication-factory=example-krb-http-auth)

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 for more information. In addition, the login module should be configured as follows:

/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=[principal=host/testserver@MY_REALM, keyTab="file:///root/keytab", credsType=acceptor])

reload

For a complete list of options for configuring the Kerberos login module, see the JBoss EAP Login Module Reference.

Configure the 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. There also must be a way to search for the roles to apply to the user. This can be accomplished in many different ways, for example by 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, see the JBoss EAP 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, see the JBoss EAP Management CLI Guide.

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/HOST_NAME.

The following are the steps to delete the existing mappings:

setspn -L MACHINE_NAME

setspn -D HTTP/HOST_NAME MACHINE_NAME

setspn -D host/HOST_NAME 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 HOST_NAME.

Run the following command to configure the service principal mapping:

ktpass -princ HTTP/HOST_NAME@REALM -pass * [-kvno 0] -mapuser DOMAIN\USER_NAME -out jboss.keytab -ptype KRB5_NT_PRINCIPAL -crypto all

Enter the password for the user name, when prompted.

Verify the mapping by running the following command: setspn -L USER_NAME.

Define the principal within the security domain.

The principal can be defined or updated in the elytron or legacy security subsystem to HTTP/HOST_NAME@REALM.