Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

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 a Keberos/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 via this method.

Note

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

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

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

    You can use the following commands to configure the security domains required by the FORM login authentication mechanism. For full instructions, see the previous section for the steps required to configure JBoss EAP and web applications to use Kerberos and SPNEGO for authentication and authorization. 

    /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=[password-stacking=useFirstPass, serverSecurityDomain=host])

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

reload

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

    • Add a new security domain to serve as a fallback authentication method. 

      /subsystem=security/security-domain=app-fallback:add(cache-type=default)

/subsystem=security/security-domain=app-fallback/authentication=classic:add()

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

    • Add a usernamePasswordDomain module option to the web application security domain that points to the fallback domain. 

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

    • Reload the server for the changes to take effect. 

      reload

    • After completing the above steps the following configuration is created.

      Example: Security Domain Configured with a Fallback Security Domain

      <security-domain name="app-spnego" cache-type="default">
  <authentication>
    <login-module code="SPNEGO" flag="requisite">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="serverSecurityDomain" value="host"/>
      <module-option name="usernamePasswordDomain" value="app-fallback"/>
    </login-module>
    <!--login module for mapping roles -->
    <login-module code="UsersRoles" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="usersProperties" value="file:${jboss.server.config.dir}/users.properties"/>
      <module-option name="rolesProperties" value="file:${jboss.server.config.dir}/roles.properties"/>
    </login-module>
  </authentication>
</security-domain>
<security-domain name="app-fallback" cache-type="default">
  <authentication>
    <login-module code="UsersRoles" flag="required">
      <module-option name="usersProperties" value="file:${jboss.server.config.dir}/fallback-users.properties"/>
      <module-option name="rolesProperties" value="file:${jboss.server.config.dir}/fallback-roles.properties"/>
    </login-module>
  </authentication>
</security-domain>

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

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

    Example error.jsp file:

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

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

    <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>examplesWebApp</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,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>All</role-name>
  </security-role>
</web-app>

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. To enable Kerberos authentication on the management interfaces, the following steps must be performed:

Note

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.

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

    Important

    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 CLI for Adding Kerberos Authentication to a Security Realm

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

reload

    Important

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

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

    Example Security Realm with Multiple Kerberos Server Identities

    <security-realm name="ManagementRealm">
  <server-identities>
    <kerberos>
      <keytab principal="HTTP/hostname@MY-REALM" path="/home/username/http.keytab" debug="true"/>
      <keytab principal="remote/hostname@MY-REALM" path="/home/username/remote.keytab" debug="true"/>
    </kerberos>
  </server-identities>
  <authentication>
    <local default-user="$local" skip-group-loading="true"/>
    <kerberos/>
    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
  </authentication>
  ...
</security-realm>

3.2.1. 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, it will attempt authenticate the user using any of the subsequent methods specified in the <authentication> element.

When you connect to the web-based management console via 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 -Djavax.security.auth.useSubjectCredsOnly=false parameter, as this allows the GSSAPI implementation to make use of the identity managed at the OS level. You may also need to use the following parameters based on how your environment is setup:

-Djava.security.krb5.realm=REALM-NAME
Specifies the realm name.
-Djava.security.krb5.kdc=KDC-HOSTNAME
Specifies the location of the KDC
--no-local-auth
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

./jboss-cli.sh -c -Djavax.security.auth.useSubjectCredsOnly=false --no-local-auth

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 EJBs. 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 Guide.

    Example Security Domain with Remoting and RealmDirect Login Modules

    <security-domain name="krb-remoting-domain">
  <authentication>
    <login-module code="Remoting" flag="optional">
      <module-option name="password-stacking" value="useFirstPass"/>
    </login-module>
    <login-module code="RealmDirect" flag="required">
      <module-option name="password-stacking" value="useFirstPass"/>
      <module-option name="realm" value="krbRealm"/>
    </login-module>
  </authentication>
  <mapping>
      <mapping-module code="SimpleRoles" type="role">
          <module-option name="testUser" value="testRole"/>
      </mapping-module>
  </mapping>
</security-domain>

  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

    <security-realm name="krbRealm">
    <server-identities>
        <kerberos>
            <keytab principal="remote/localhost@JBOSS.ORG" path="/path/to/remote.keytab" debug="true"/>
        </kerberos>
    </server-identities>
    <authentication>
        <kerberos remove-realm="true"/>
        <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
    </authentication>
</security-realm>

  3. Configure the HTTP connector in the remoting subsystem to use the security realm

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

    Example Remoting

    <subsystem xmlns="urn:jboss:domain:remoting:3.0">
  <endpoint/>
  <http-connector name="http-remoting-connector" connector-ref="default" security-realm="krbRealm"/>
</subsystem>

  4. Configure security for the service

    You will also need to setup the service that is accessed via the remoting interface to secured. This will vary depending on the service. For example, with an EJB you could use the @SecurityDomain, org.jboss.ejb3.annotation.SecurityDomain, and @RolesAllowed, javax.annotation.security.RolesAllowed, annotations.





Revised on 2018-02-08 10:16:50 EST