How to Set Up SSO with Kerberos

Authentication exchange.

When a principal first accesses the network or attempts to access a secured service without a ticket granting ticket (TGT), they are challenged to authenticate against the authentication service (AS) 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 or resources. The principal sends a request to the ticket granting service (TGS), passing the TGT it was issued by the KDC and requesting a service ticket (ST) 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, the client may now establish a connection and attempt to access the secured resource. The client starts by passing the ST to the destination server. This ST contains the server component of the session information which 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 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.

Configure JBoss EAP and the web application to use Kerberos and SPNEGO.

See How to Set Up SSO for JBoss EAP with Kerberos for the steps required to configure JBoss EAP and web applications to use Kerberos and SPNEGO for authentication and authorization. ⁠

Add the login and error pages.

To use FORM login, a login and error page are required. These files are added to web application and are used in the authentication process.

<html>
  <head></head>
  <body>
    <form id="login_form" name="login_form" method="post" action="j_security_check" enctype="application/x-www-form-urlencoded">
      <center> <p>Please login to proceed.</p> </center>
      <div style="margin-left: 15px;">
        <p> <label for="username">Username</label> <br /> <input id="username" type="text" name="j_username"/> </p>
        <p> <label for="password">Password</label> <br /> <input id="password" type="password" name="j_password" value=""/> </p>
        <center> <input id="submit" type="submit" name="submit" value="Login"/> </center>
      </div>
    </form>
  </body>
</html>

<html>
  <head></head>
  <body>
    <p>Login failed, please go back and try again.</p>
  </body>
</html>

Modify the web.xml.

After adding the login and error pages to the web application, the web.xml must be updated to use these files for FORM login. The exact value FORM must be added to the <auth-method> element. Since <auth-method> expects a comma-separated list and order is significant, the exact value for <auth-method> must be updated to SPNEGO,FORM. In addition, a <form-login-config> element must be added to <login-config> and the paths to the login and error pages specified as <form-login-page> and <form-error-page> elements.

<web-app>
  <display-name>App1</display-name>
  <description>App1</description>
  <!-- Define a security constraint that requires the Admin role to access resources -->
  <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>Admin</role-name>
    </auth-constraint>
  </security-constraint>
  <!-- Define the Login Configuration for this Application -->
  <login-config>
    <auth-method>SPNEGO,FORM</auth-method>
    <realm-name>SPNEGO</realm-name>
    <form-login-config>
      <form-login-page>/login.jsp</form-login-page>
      <form-error-page>/error.jsp</form-error-page>
    </form-login-config>
  </login-config>
  <!-- Security roles referenced by this web application -->
  <security-role>
    <description> role required to log in to the Application</description>
    <role-name>Admin</role-name>
  </security-role>
</web-app>

Add a mechanism for FORM authentication in the http-authentication-factory.

You can use the existing http-authentication-factory you configured for kerberos-based authentication and an additional mechanism for FORM authentication.

/subsystem=elytron/http-authentication-factory=example-krb-http-auth:list-add(name=mechanism-configurations, value={mechanism-name=FORM})

Add additional fallback principals.

The existing configuration for kerberos-based authentication should already have a security realm configured for mapping principals from kerberos token to roles for the application. You can add additional users for fallback authentication to that realm. For example if you used a filesystem-realm, you can simply create a new user with the appropriate roles:

/subsystem=elytron/filesystem-realm=exampleFsRealm:add-identity(identity=fallbackUser1)

/subsystem=elytron/filesystem-realm=exampleFsRealm:set-password(identity=fallbackUser1, clear={password="password123"})

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

Follow the same instructions for configuring Kerberos authentication for applications to create an http-authentication-factory that does Kerberos authentication.

Update the management HTTP interface to use the http-authentication-factory.

/core-service=management/management-interface=http-interface:write-attribute(name=http-authentication-factory, value=example-krb-http-auth)

Add GSSAPI to the configurable-sasl-server-factory.

/subsystem=elytron/configurable-sasl-server-factory=configured:list-add(name=filters, value={pattern-filter=GSSAPI})

Create a sasl-authentication-factory that uses the security domain and kerberos-security-factory.

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

Update the management SASL interface to use the sasl-authentication-factory.

/core-service=management/management-interface=http-interface:write-attribute(name=http-upgrade.sasl-authentication-factory, value=example-sasl-auth)

reload

Enable the relevant system properties.

As discussed in a previous section, enable any needed JBoss EAP system properties for connecting to the Kerberos server.

Add the Kerberos server identity to the security realm.

Before Kerberos authentication can be used in a security realm, a connection to a Kerberos server must be added. The following example shows how to add a Kerberos server identity to the existing Management Realm. You will need to replace service-name, hostname, and MY-REALM with the appropriate values.

/core-service=management/security-realm=ManagementRealm/server-identity=kerberos:add()

/core-service=management/security-realm=ManagementRealm/server-identity=kerberos/keytab=service-name\/hostname@MY-REALM:add(path=/home\/username\/service.keytab, debug=true)

reload

Update the authentication method in the security realm.

Once the Kerberos server identity has been properly configured, the authentication method in the security realm needs to be updated to use it.

/core-service=management/security-realm=ManagementRealm/authentication=kerberos:add()

reload

Secure both interfaces with Kerberos.

In cases where you would like to secure both the web-based management console and management CLI with Kerberos, you need a Kerberos server identity configured for each. To add an additional identity, use the following command.

/core-service=management/security-realm=ManagementRealm/server-identity=kerberos/keytab=remote\/hostname@MY-REALM:add(path=/home\/username\/remote.keytab, debug=true)

reload

Configure a security domain with remoting and RealmDirect

You need to configure a security domain for use by the service that is accessed by remoting. This security domain needs to make use of both the Remoting login module as well as a RealmDirect login module, such as RealmDirect or RealmUsersRoles. Essentially, it should look very similar to the other security domain provided by default. For more details on the specific configuration options of each login module, see the JBoss EAP Login Module Reference.

/subsystem=security/security-domain=krb-remoting-domain:add()

/subsystem=security/security-domain=krb-remoting-domain/authentication=classic:add()

/subsystem=security/security-domain=krb-remoting-domain/authentication=classic/login-module=Remoting:add(code=Remoting, flag=optional, module-options=[password-stacking=useFirstPass])

/subsystem=security/security-domain=krb-remoting-domain/authentication=classic/login-module=RealmDirect:add(code=RealmDirect, flag=required, module-options=[password-stacking=useFirstPass, realm=krbRealm])

/subsystem=security/security-domain=krb-remoting-domain/mapping=classic:add()

/subsystem=security/security-domain=krb-remoting-domain/mapping=classic/mapping-module=SimpleRoles:add(code=SimpleRoles, type=role, module-options=["testUser"="testRole"])

reload

Configure a security realm for Kerberos authentication.

Setting up a security realm with Kerberos authentication is covered in the Securing the Management Interfaces with Kerberos section.

/core-service=management/security-realm=krbRealm:add()

/core-service=management/security-realm=krbRealm/server-identity=kerberos:add()

/core-service=management/security-realm=krbRealm/server-identity=kerberos/keytab=remote\/localhost@JBOSS.ORG:add(path=\/path\/to\/remote.keytab, debug=true)

/core-service=management/security-realm=krbRealm/authentication=kerberos:add(remove-realm=true)

reload

Configure the HTTP connector in the remoting subsystem.

In addition, you will need to configure the HTTP connector in the remoting subsystem to use the newly created security realm.

/subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=security-realm, value=krbRealm)

Configure security for the service.

You must also set up the service that is accessed using the remoting interface to secured. This will vary depending on the service. For example, with an EJB, you can use the @SecurityDomain and @RolesAllowed annotations.

Define the security realm to load the identity from. It is used for assigning roles.

/path=kerberos:add(relative-to=user.home, path=src/kerberos)

/subsystem=elytron/properties-realm=kerberos-properties:add(users-properties={path=kerberos-users.properties, relative-to=kerberos, digest-realm-name=ELYTRON.ORG}, groups-properties={path=kerberos-groups.properties, relative-to=kerberos})

Define the Kerberos security factory for the server’s identity.

/subsystem=elytron/kerberos-security-factory=test-server:add(relative-to=kerberos, path=remote-test-server.keytab, principal=remote/test-server.elytron.org@ELYTRON.ORG)

Define the security domain and along with it, a SASL authentication factory.

/subsystem=elytron/security-domain=KerberosDomain:add(default-realm=kerberos-properties, realms=[{realm=kerberos-properties, role-decoder=groups-to-roles}], permission-mapper=default-permission-mapper)

/subsystem=elytron/sasl-authentication-factory=gssapi-authentication-factory:add(security-domain=KerberosDomain, sasl-server-factory=elytron, mechanism-configurations=[{mechanism-name=GSSAPI, credential-security-factory=test-server}])

Use the created sasl-authentication-factory, in the remoting subsystem, to enable it for remoting.

/subsystem=remoting/http-connector=http-remoting-connector:write-attribute(name=sasl-authentication-factory, value=gssapi-authentication-factory)

Configure security for the service.

If you reference the security domain in an EJB, you must specify the application-security-domain that maps to the Elytron security domain. For example, with an EJB, you can use the @SecurityDomain annotation.

/subsystem=ejb3/application-security-domain=KerberosDomain:add(security-domain=KerberosDomain)