Chapter 2. How to Set Up SSO for JBoss EAP with Kerberos
This section covers how to configure JBoss EAP and the deployed applications to use Kerberos for SSO.
The following components are needed for setting SSO for JBoss EAP with Kerberos:
- A properly configured Kerberos environment
- A JBoss EAP instance
- A web application
2.1.1. JBoss Negotiation Toolkit
The JBoss Negotiation Toolkit is a debugging tool to help users debug and test authentication mechanisms before introducing an application into production. It is an unsupported tool but can be very helpful, as SPNEGO can be difficult to configure for web applications.
You can download a prebuilt WAR file of the JBoss Negotiation Toolkit here. You should download the version of JBoss Negotiation Toolkit that matches the version of JBoss Negotiation included in JBoss EAP. For example, if you are using JBoss EAP 7.0.0, which uses JBoss Negotiation
3.0.2.Final-redhat-1, you should use
jboss-negotiation-toolkit-3.0.2.Final.war. You can determine which version of JBoss Negotiation is being used by looking at
2.1.2. Kerberos Environment
As discussed in a previous section, Kerberos relies on a third party, the KDC, to provide authentication and authorization decisions. This also requires clients, for example browsers, and their host to be properly configured to authenticate with the KDC. This guide is primarily focused on how to configure JBoss EAP and its hosted web applications so configuring the KDC and Kerberos domain are not in the scope of this document.
The subsequent sections assume a KDC and Kerberos domain have already been set up and properly configured.
2.1.3. Differences from Configuring Previous Versions JBoss EAP
There are a few noticeable differences between JBoss EAP 7 and earlier versions:
The NegotiationAuthenticator valve is no longer required in the
jboss-web.xml, but there still must be a
<login-config>elements to be defined in the
web.xml. These are used to decide which resources are secured.
auth-methodelement in the
<login-config>element is now a comma-separated list. The exact value
SPNEGOmust be there and should appear first in that list. In cases where
FORMauthentication is desired as a fallback, the exact value would be
2.1.4. Configuring the JBoss EAP Instance
JBoss EAP comes with all the components necessary to use Kerberos, using SPNEGO and JBoss Negotiation, for SSO with deployed applications, but the following configuration changes need to be made:
The management CLI commands shown assume that you are running a JBoss EAP standalone server. For more details on using the management CLI for a JBoss EAP managed domain, please see the JBoss EAP Management CLI Guide.
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.
Example CLI for Creating a Server Identity Security Domain
/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:
IBM JDK Example
<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
Kerberoslogin 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.
Example CLI for Creating a Server Identity 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
SPNEGOlogin 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>
The host name of the KDC
The name of the realm
The path to the configuration
When set to
true, disables automatic adding of
jboss.security.security_domainlogin module option to login modules declared in the security domain. Must be set to
truewhen using the IBM JDK
true, debugging mode will be enabledNote
By default, each login module defined in a security domain has the
jboss.security.security_domainmodule option added to it automatically. This option causes problems with login modules which check to make sure that only known options are defined. The IBM Kerberos login module,
com.ibm.security.auth.module.Krb5LoginModuleis one of these. This behavior of adding this module option can disabled by setting the
jboss.security.disable.secdomain.optionsystem property to
truewhen starting JBoss EAP. This can be accomplished by configuring the
<system-properties>, using the Management CLI or Management Console, or by adding
-Djboss.security.disable.secdomain.option=trueto the start-up parameters.
For more information about configuring system properties, refer to the Red Hat JBoss Enterprise Application Platform Management CLI Guide.
2.1.5. Configuring the Web Application
Once the security domains have been configured, the web application must be configured to use those security domains in order to enable Kerberos authentication. Once the application changes have been made, it may be deployed to the JBoss EAP instance and begin using Kerberos for authentication.
The following updates must be made the application:
web.xmlto use the SPNEGO authentication method.
web.xmlfile should contain the following:
<url-pattern>that maps to the URL pattern of the secured area. Optionally,
<security-constraint>may also contain an
<auth-constraint>stipulating the allowed roles.
If any roles were specified in the
<auth-constraint>, those roles should be defined in a
<auth-method>with the exact value of
<auth-method>element expects a comma-separated list of specific values. For
SPNEGOauthentication to be properly configured, the exact value
SPNEGOmust appear in the
<auth-method>element and should appear first. Incorporating additional authentication types is discussed in a later section.
<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>
jboss-web.xmlto use the configured security domain.
jboss-web.xmlfile should have the following:
<security-domain>to specify which security domain to use for authentication and authorization.
<jacc-star-role-allow>, which enables the use of the asterisk character in role-name element in
web.xmlto match multiple role names.
<jboss-web> <security-domain>app-spnego</security-domain> <jacc-star-role-allow>true</jacc-star-role-allow> </jboss-web>
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.xmlso 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.
Using jboss-deployment-structure.xml to declare dependencies
<jboss-deployment-structure> <deployment> <dependencies> <module name="org.jboss.security.negotiation"/> </dependencies> </deployment> </jboss-deployment-structure>
Alternatively, this dependency may be defined in a
Using META-INF/MANIFEST.MF to declare dependencies
Manifest-Version: 1.0 Dependencies: org.jboss.security.negotiation
2.2. Additional Considerations for Active Directory
This section describes how to configure the accounts required for JBoss Negotiation to be used when JBoss EAP is running on a Microsoft Windows server, which is a part of the Active Directory domain.
In this section, the hostname that is used to access the server as is referred to as
HOSTNAME, realm is referred to as
REALM, domain is referred to as
DOMAIN, and the server hosting the JBoss EAP instance is referred to as
2.2.1. Configure JBoss Negotiation for Microsoft Windows Domain
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/
The following are the steps to delete the existing mappings:
List the mapping registered with the domain for the computer using the command:
setspn -L MACHINE_NAME
Delete the existing mappings using the commands:
setspn -D HTTP/HOST_NAME MACHINE_NAME
setspn -D host/HOSTNAME MACHINE_NAME
Create a host user account.Note
Ensure the host user name is different from the
In the rest of the section the host user name is referred to as
Define the mapping between the
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.Note
Reset the password for the user name as it is a prerequisite for exporting the keytab.
Verify the mapping by running the following command, setspn -L
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@REALMNote
This command exports the ticket for the HTTP/
HOSTNAMEprincipal to the keytab service.keytab, which is used to configure the host security domain on JBoss EAP.
Define the principal within the security domain.
The principal can be defined or updated in the security domain as follows: