JBoss Community

Securing the JMX Console and Web Console

Both the jmx-console and web-console are standard servlet 2.3 deployments and can

be secured using J2EE role based security. Both also have a skeleton setup to allow

one to easily enable security using username/password/role mappings found in the

jmx-console.war and web-console.war deployments in the corresponding WEB-INF/classes

users.properties and roles.properties files.

The security setup is based on two pieces, the standard WEB-INF/web.xml servlet URI

to role specification, and the WEB-INF/jboss-web.xml specification of the JAAS configuration which defines how authentication and role mapping is performed.

To secure the JMX Console using a username/password file -

• Locate the jmx-console.war directory.  This will normally be in ${jboss.server.home.dir}/deploy directory.

• Edit WEB-INF/web.xml and uncomment the security-constraint block.

• Edit WEB-INF/classes/jmx-console-users.properties or server/default/conf/props/jmx-console-users.properties (version >=4.0.2) and WEB-INF/classes/jmx-console-roles.properties or server/default/conf/props/jmx-console-roles.properties (version >=4.0.2) and change the users and passwords to what you desire.  They will need the JBossAdmin role specified in the web.xml file to run the JMX Console.

• Edit WEB-INF/jboss-web.xml and uncomment the security-domain block. The security-domain value of jmx-console maps is declared in the login-config.xml JAAS configuration file which defines how authentication and authorization is done.

To secure the JMX Console using your own JAAS domain -

• Edit WEB-INF/web.xml as above, uncommenting the security-constraint block.  Change the role-name value to be the role in your domain that can access the console.

• Edit WEB-INF/jboss-web.xml as above, setting the security domain to be the name of your security domain.  For example, if your login-config.xml has an application-policy whose name is MyDomain then your JAAS domain java:/jaas/MyDomain.

• After making all the changes, redeploy the application.  The application can be redeployed by touching the web.xml file or by restarting the server.

The process to secure the web console is similar.  In the deploy directory, locate management/web-console.war and make the same changes as above to to WEB-INF/web.xml, WEB-INF/jboss-web.xml and the users/groups properties file.  The default JAAS domain used by the web-console is java:/jaas/web-console and is defined in login-config.xml in the conf directory.  You can use a custom JAAS domain or customize the existing domain in the same way as with the JMX console. Typically you would just use the same domain (java:/jaas/jmx-console) as the jmx-console so that you have a single user/role mapping to configurue.

If you find as I did with 3.2.5 that I couldn't log in, another users.properties is most likely being picked up. Change the web-console login-config.xml entry so that that properties files are uniquely named to avoid ambiguity with which resource is picked up. You also would need to rename the web-console properties files. (see http://www.jboss.org/index.html?module=bb&op=viewtopic&t=53346 )

As an extra level of security you may also want to Limit Access to Certain Clients in a particular IP address range.

Update for 4.0.2

The jmx-console-roles.properties  and jmx-console-users.properties files have been moved to ${jboss.server.home.dir}/conf/props. This is because of the change to use the servlet 2.3 class loading model and these properties files would not be visible to the other deployments using the jmx-console security domain. You can move the files from conf/props to WEB-INF/classes, or leave them in place and edit the password for admin.

Similarly for the web console, please note that the web console is unpacked already in the server configuration as deploy/management/console-mgr.sar/web-console.war. Proceed to edit the WEB-INF/web.xml and jboss-web.xml files as per securing the JMX console, and either edit the WEB-INF/classes/web-console-roles.properties and web-console-users.properties, or move those files to ${jboss.server.home.dir}/conf/props and edit them there.

For the impatient

vi ${jboss.server.home.dir}/deploy/jmx-console.war/WEB-INF/web.xml

uncomment the security-constraint block

and add a <login-config> block after the end of the <security-constraint> block:

<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>JMXConsole</realm-name>
</login-config>

vi ${jboss.server.home.dir}/deploy/jmx-console.war/WEB-INF/jboss-web.xml

Uncomment the security-domain block. Make sure the JNDI name maps to the realm name (i.e. JMXConsole)

vi ${jboss.server.home.dir}/conf/props/jmx-console-users.properties

change the password for admin

vi ${jboss.server.home.dir}/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml

uncomment the security-constraint block

and add a <login-config> block after the end of the <security-constraint> block:

<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>JMXConsole</realm-name>
</login-config> 

vi ${jboss.server.home.dir}/deploy/management/console-mgr.sar/web-console.war/WEB-INF/jboss-web.xml

Uncomment the security-domain block. Make sure the JNDI name maps to the realm name (e.g. JMXConsole)

vi ${jboss.server.home.dir}/conf/login-config.xml

Change the path to the web-console-users.properties and the web-console-roles.properties as follows (add props/ to the front of the path)

<module-option name="usersProperties">props/web-console-users.properties</module-option>
<module-option name="rolesProperties">props/web-console-roles.properties</module-option>

cp ${jboss.server.home.dir}/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/web-console-.properties ${jboss.server.home.dir}/conf/props

edit as needed

cp ${jboss.server.home.dir}/conf/props/jmx-console-roles.properties ${jboss.server.home.dir}/conf/props/web-console-roles.properties

edit as needed

edit ${jboss.server.home.dir}/conf/login-config.xml, find the jmx-console and web-console applicaiton-policy, and set the name to jmx-console and web-console, respectively. That is make sure that the application policy name maps to the realm name (i.e. JMXConsole)

restart jboss

Additional to secure jmx-console and web-console authentication via SSL

• must perform the above steps to enable http authenication ...

   the following steps below will redirect jboss admin pages to https://localhost:8443

• edit both web.xml to include the following just before end of tag security-constraint

<security-constraint>
    ...      
  <user-data-constraint>      
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint> 

• generate /data01/jboss/server/xxxx/conf/keystore and select your own new secure password (@see Creating an SSL Keystore Using the Java Keytool)

or quick setup and verify:

$ keytool -genkey -keystore /data01/jboss/server/xxx/conf/keystore -alias jbossAdmin
$ keytool -list -keystore /data01/jboss/server/xxx/conf/keystore

$ vi /data01/jboss/server/xxx/deploy/jbossweb-tomcat50.sar/server.xml

• secure file permission via chmod 600 server.xml
• uncomment section "SSL/TLS Connector" to enable Connector port="8443"
• replace keystoreFile="${jboss.server.home.dir}/conf/chap8.keystore" with  keystoreFile="${jboss.server.home.dir}/conf/keystore"

• replace keystorePass="rmi+ssl" sslProtocol = "TLS" /> with keystorePass="<your new secure password>" sslProtocol = "TLS" />

Technical White Paper

Technical White Paper on Securing JMX (jboss-secure.jmx.html attached)