Chapter 2. Configure the Admin Console

2.1. Security

The Admin Console is secured by the JAAS security domain jmx-console. When the Enterprise Application Platform is installed using the zip archive, this security domain has no user accounts. This is to eliminate the possibility of default username/password based attacks. When the Enterprise Application Platform is installed using the Graphical Installer, a JAAS security domain and a user account is created as part of the install process. Even if the name of the JAAS security domain was changed during installation, the users are stored in the same location.

2.1.1. Authentication

Authentication is the process where a user identifies themselves to a system. The Admin Console makes use of username/password authentication, with permissions and roles assigned to users via the jmx-console and jboss-web domains.

2.1.2. Enable Authentication

The Enterprise Application Platform ships with authentication on the default security domains enabled by default. In order to check that authentication is enabled, or re-enable authentication that has previously been disabled, follow this procedure. For more information on security domains and authentication in the Enterprise Application Platform, refer to the Security Guide.

Procedure 2.1. Enabling Authentication

  1. Enabling Authentication on the JMX console

    In this web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/jmx-console.war/WEB-INF/web.xml
    ensure the following security-constraint fragment is uncommented.
    <security-constraint>
       <web-resource-collection>
          <web-resource-name>HtmlAdaptor</web-resource-name>
          <description>
             An example security config that only allows users with the role
             JBossAdmin to access the HTML JMX console web application
          </description>
          <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
        <role-name>JBossAdmin</role-name>
      </auth-constraint>
    </security-constraint>
    
  2. Enabling Security Domain on the JMX console

    In this jboss-web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/jmx-console.war/WEB-INF/jboss-web.xml
    ensure the following fragment is included.
    <jboss-web>
      <!-- Uncomment the security-domain to enable security. You will
         need to edit the htmladaptor login configuration to setup the
         login modules used to authentication users.
      -->
      <security-domain>java:/jaas/jmx-console</security-domain>
    </jboss-web>
    
  3. Enabling Authentication on the Admin Console

    In this web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml
    ensure the following security-constraint fragment is uncommented.
    <security-constraint>
       <web-resource-collection>
          <web-resource-name>HtmlAdaptor</web-resource-name>
          <description>
             An example security config that only allows users with the role
             JBossAdmin to access the HTML JMX console web application
          </description>
          <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
        <role-name>JBossAdmin</role-name>
      </auth-constraint>
    </security-constraint>
    
  4. Enabling Security Domain on the Admin Console

    In this jboss-web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web.console.war/WEB-INF/jboss-web.xml
    ensure the following fragment is included.
    <jboss-web>
      <!-- Uncomment the security-domain to enable security. You will
         need to edit the htmladaptor login configuration to setup the
         login modules used to authentication users.
      -->
      <security-domain>java:/jaas/jmx-console</security-domain>
    </jboss-web>
    

2.1.3. Users and Roles

The Enterprise Application Platform uses Roles to enable and restrict access to the Admin Console. Specifically, the roles allocated to users of the Admin Console are the JBossAdmin and HttpInvoker roles, as detailed in the procedure.

Procedure 2.2. Creating a User

This procedure creates a user, then grants the user permission to access the Admin Console and HTTP Invoker.
  1. Create a user in the jmx-console JAAS security domain

    Edit the file jmx-console-users.properties in the directory JBOSS_HOME/server/PROFILE/conf/props/.
    1. Create a username and password

      Create a username = password pair.

      Important

      The commented admin=admin username and password is an example of the username/password definition syntax. Do not use this for your user account.
  2. Create a user in the web-console JAAS security domain

    1. Edit the file web-console-users.properties in the directory JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/.
    2. Add username and password

      Add the username = password pair.

      Important

      The commented admin=admin username and password is an example of the username/password definition syntax. Do not use this for your user account.
  3. Grant web console permissions to user

    1. Edit the file web-console-roles.properties in the directory JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/.
    2. Create an entry for the user of the form:
      username=JBossAdmin,HttpInvoker
      
      JBossAdmin
      Grant the user permission to access the Web-Console
      HttpInvoker
      Grant the user permission to access the HTTP Invoker
  4. Grant JMX console permissions to user

    1. Edit the file jmx-console-roles.properties in the directory JBOSS_HOME/server/PROFILE/conf/props/.
    2. Create an entry for the user of the form:
      username=JBossAdmin,HttpInvoker
      
      JBossAdmin
      Grant the user permission to access the Web-Console
      HttpInvoker
      Grant the user permission to access the HTTP Invoker

2.1.4. Disable Authentication

Authentication can be disabled for use in development environments, where the installation is on a secure, internal machine.

Warning

Do not disable authentication on an externally-facing installation.

Procedure 2.3. Disabling Authentication

  1. Disable security constraints on the JMX Console

    In this web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/jmx-console.war/WEB-INF/web.xml
    comment out the security-constraint fragment.
    <security-constraint>
       <web-resource-collection>
          <web-resource-name>HtmlAdaptor</web-resource-name>
          <description>
             An example security config that only allows users with the role
             JBossAdmin to access the HTML JMX console web application
          </description>
          <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
        <role-name>JBossAdmin</role-name>
      </auth-constraint>
    </security-constraint>
    
  2. Disabling Security Domain on the JMX Console

    In this jboss-web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/jmx-console.war/WEB-INF/jboss-web.xml
    remove the following fragment.
    <jboss-web>
      <!-- Uncomment the security-domain to enable security. You will
         need to edit the htmladaptor login configuration to setup the
         login modules used to authentication users.
      -->
      <security-domain>java:/jaas/jmx-console</security-domain>
    </jboss-web>
    
  3. Disable security constraints on the Web Console

    In this web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml
    comment out the security-constraint fragment.
    <security-constraint>
       <web-resource-collection>
          <web-resource-name>HtmlAdaptor</web-resource-name>
          <description>
             An example security config that only allows users with the role
             JBossAdmin to access the HTML JMX console web application
          </description>
          <url-pattern>/*</url-pattern>
      </web-resource-collection>
      <auth-constraint>
        <role-name>JBossAdmin</role-name>
      </auth-constraint>
    </security-constraint>
    
  4. Disabling Security Domain for the Web Console

    In this jboss-web.xml file:
    • JBOSS_HOME/server/PROFILE/deploy/management/console-mgr.sar/web.console.war/WEB-INF/jboss-web.xml
    remove the following fragment.
    <jboss-web>
      <!-- Uncomment the security-domain to enable security. You will
         need to edit the htmladaptor login configuration to setup the
         login modules used to authentication users.
      -->
      <security-domain>java:/jaas/jmx-console</security-domain>
    </jboss-web>