Chapter 3. Additional Features

3.1. Adding a FORM Login as a Fallback

JBoss EAP and applications deployed to it can also configure a FORM login authentication mechanism to use as a fallback. This allows applications to present a login page for authentication in cases where Kerberos/SPNEGO tokens are not present. This authentication happens independent of the Kerberos authentication. As a result, depending on how the FORM login fallback is configured, users may require separate credentials to authenticate by this method.


The fallback to FORM login is available when no SPNEGO or NTLM tokens are present or, when a SPNEGO token is present, but from another KDC.

3.1.1. Update Your Application

The following steps are required to configure your application for FORM login as a fallback:

  1. 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. ⁠

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

    Example: login.jsp File

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

    Example: error.jsp File

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

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

    Example: Updated web.xml File

      <!-- Define a security constraint that requires the Admin role to access resources -->
        <display-name>Security Constraint on Conversation</display-name>
      <!-- Define the Login Configuration for this Application -->
      <!-- Security roles referenced by this web application -->
        <description> role required to log in to the Application</description>

3.1.2. Update the Elytron Subsystem

  1. 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})
  2. 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:set-password(identity=fallbackUser1, clear={password="password123"})

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

3.1.3. Update the Legacy Security Subsystem

If you are using the legacy security subsystem in JBoss EAP, you must update the security domain for fallback authentication.

The web application security domain must be configured to support a fallback login mechanism. This requires the following steps:

  1. Add a new security domain to serve as a fallback authentication method.
  2. Add a usernamePasswordDomain module option to the web application security domain that points to the fallback domain.

Example: Security Domain Configured with a Fallback Security Domain



/subsystem=security/security-domain=app-fallback/authentication=classic/login-module=UsersRoles:add(code=UsersRoles, flag=required, module-options=[usersProperties="file:${jboss.server.config.dir}/", rolesProperties="file:${jboss.server.config.dir}/"])

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

/subsystem=security/security-domain=app-spnego/authentication=classic/login-module=SPNEGO:map-put(name=module-options, key=usernamePasswordDomain, value=app-fallback)

/subsystem=security/security-domain=app-spnego/authentication=classic/login-module=SPNEGO:map-put(name=module-options, key=password-stacking, value=useFirstPass)


3.2. Securing the Management Interfaces with Kerberos

In addition to providing Kerberos authentication in security domains, JBoss EAP also provides the ability to secure the management interfaces using Kerberos.

3.2.1. Secure the Management Interfaces with Kerberos Using Elytron

To configure Kerberos authentication for the HTTP management interface:

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


    When configuring Kerberos authentication with the management interfaces, it is very important that you pay close attention to the service principal you configure for JBoss EAP to authenticate against the KDC. This service principal takes the form of service-name/hostname. JBoss EAP expects HTTP to be the service name, for example HTTP/localhost, when authenticating against the web-based management console and remote to be the service name, for example remote/localhost, for the management CLI.

  2. 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)

To configure Kerberos authentication for SASL authentication for the management CLI:

  1. Follow the same instructions for configuring Kerberos authentication for applications to create a security domain and kerberos-security-factory.
  2. Add GSSAPI to the configurable-sasl-server-factory.

    /subsystem=elytron/configurable-sasl-server-factory=configured:list-add(name=filters, value={pattern-filter=GSSAPI})
  3. Create a sasl-authentication-factory that uses the security domain and kerberos-security-factory.

    Example: sasl-authentication-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}])

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

    Example: Update sasl-authentication-factory

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

3.2.2. Secure the Management Interfaces With Kerberos Using Legacy Core Management Authentication

To enable Kerberos authentication on the management interfaces using legacy core management authentication, the following steps must be performed:


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, see the JBoss EAP Management CLI Guide.

  1. Enable the relevant system properties.

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

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

    Example CLI for Adding a Server Identity to a Security Realm

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


    When configuring Kerberos authentication with the management interfaces, it is very important that you pay close attention to the service principal you configure for JBoss EAP to authenticate against the KDC. This service principal takes the form of service-name/hostname. JBoss EAP expects HTTP to be the service name, for example HTTP/localhost, when authenticating against the web-based management console and remote to be the service name, for example remote/localhost, for the management CLI.

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

    Example: Adding Kerberos Authentication to a Security Realm



    Based on the order in which you have the authentication mechanisms defined in the security realm, JBoss EAP will attempt to authenticate the user in that order when accessing the management interfaces.

  4. 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)

3.2.3. Connecting to the Management Interface

Before attempting to connect to the management interfaces, you need to have a valid Kerberos ticket. If the security realm fails to authenticate a user via Kerberos, when using the legacy security solution, it will attempt to authenticate the user using any of the subsequent methods specified in the <authentication> element. The elytron subsystem behaves similar to the legacy security solution. If the Kerberos authentication mechanism fails, authentication falls back to any other mechanism that you have defined in the authentication factory that is protecting the management interface. Usually, DIGEST or BASIC is used as a fallback.

When you connect to the web-based management console using a browser, the security realm will attempt to authenticate you based on that ticket.

When connecting to the management CLI, you will need to use the parameter, as this allows the GSSAPI implementation to make use of the identity managed at the operating system level. You may also need to use the following parameters based on how your environment is set up:
Specifies the realm name.
Specifies the location of the KDC.
Disables local authentication. This is useful if you are attempting to connect to a JBoss EAP instance running on the same machine you are running the script from.

Example Command

$ EAP_HOME/bin/ -c --no-local-auth


If an HTTP proxy is used between the client and server, it must take care to not share authenticated connections between different authenticated clients to the same server. If this is not honored, then the server can easily lose track of security context associations. A proxy that correctly honors client to server authentication integrity will supply the Proxy-support: Session- Based-Authentication HTTP header to the client in HTTP responses from the proxy. The client must not utilize the SPNEGO HTTP authentication mechanism through a proxy unless the proxy supplies this header with the 401 Unauthorized response from the server.

3.3. Kerberos Authentication Integration for Remoting

In addition to using Kerberos for securing the management interfaces and web applications, you can also configure Kerberos authentication for services accessed via remoting, such as Jakarta Enterprise Beans.

System properties for Kerberos also need to be configured. For more information, see Configure the Elytron Subsystem.

3.3.1. Kerberos Authentication Integration Using Legacy Security Realms

To configure Kerberos authentication, you will need to do the following:

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

    Example: Security Domain with Remoting and RealmDirect Login Modules

    /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/mapping-module=SimpleRoles:add(code=SimpleRoles, type=role, module-options=["testUser"="testRole"])

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

    Example: Security Realm

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

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

    Example: Remoting Subsystem

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

  4. 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 a Jakarta Enterprise Beans, you can use the @SecurityDomain and @RolesAllowed annotations.

3.3.2. Kerberos Authentication Integration Using Elytron

It is possible to define an Elytron security domain for Kerberos or GSSAPI SASL authentication for remoting authentication.

  1. 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={, relative-to=kerberos, digest-realm-name=ELYTRON.ORG}, groups-properties={, relative-to=kerberos})
  2. 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/
  3. 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}])
  4. Use the created sasl-authentication-factory, in the remoting subsystem, to enable it for remoting.

    Example CLI Command

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

  5. Configure security for the service.

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

    Example CLI Command


The use of a Jakarta Authentication Subject for identity association is no longer supported. Clients wishing to programmatically manage the Kerberos identity for a Jakarta Enterprise Beans call should migrate and use the AuthenticationConfiguration APIs directly, as follows:

// create your authentication configuration
AuthenticationConfiguration configuration = AuthenticationConfiguration.empty()

// create your authentication context
AuthenticationContext context = AuthenticationContext.empty().with(MatchRule.ALL, configuration);

// create a callable that looks up an Jakarta Enterprise Bean and invokes a method on it
Callable<Void> callable = () -> {

// use your authentication context to run your callable

The call to useGSSCredential(getGSSCredential()) happens when creating the AuthenticationConfiguration. Client code that already has access to a Jakarta Authentication Subject can easily be converted to obtain the GSSCredential as follows:

private GSSCredential getGSSCredential() {
    return Subject.doAs(subject, new PrivilegedAction<GSSCredential>() {

        public GSSCredential run() {
            try {
                GSSManager gssManager = GSSManager.getInstance();
                return gssManager.createCredential(GSSCredential.INITIATE_ONLY);
            } catch (Exception e) {
            return null;

Revised on 2022-06-27 13:37:23 UTC