In addition to the services made available by the running application server or servers, JBoss AS 7 also makes available two management interfaces to allow remote clients to connect for the purpose of managing the running JBoss AS 7 installation. This page describes how these interfaces are used and how they can be secured.
The two management interfaces that are exposed are a HTTP interface and a Native interface. The HTTP interface is both used to provide the GWT based administration console and also allows for management operations to be executed using a JSON encoded protocol and a de-typed RPC style API. When running a standalone server the native interface allows for management operations to be executed over a proprietary binary protocol. This is used by the supplied command line interface tool and can also be used by other remote clients that use the jars distributed with JBoss AS 7 to communicate.
When running a managed domain the use of these interfaces is slightly more complicated. On each host there will be a host controller process. On one host the host controller will be configured to act as the master domain controller; on the remaining hosts the host controller will be a slave to the master domain controller. In a managed domain the HTTP interface is still used in the same way; it allows GWT based administration console to run on the master domain controller and also allows any custom HTTP and JSON based management clients to execute management operations on any host controller. The native interface allows the command line interface tool to execute operations on the domain controller or on any host controller. The native interface however is also used for a couple of additional clients: once the host controller spawns the actual application server instances, these establish a connection back to the host controller through the native interface that it exposes, and, finally, the slave host controllers use the native interface to establish a connection back to the master domain controller to initially obtain a copy of the domain model and then to subsequently receive operations from the master domain controller.
The interfaces to be exposed are defined in the standalone.xml configuration for a standalone server and are in the host.xml configuration for a server within a managed domain. In both cases the structure of the configuration is the same.
<management>
...
<management-interfaces>
<native-interface interface="management" port="9999" />
<http-interface interface="management" port="9990"/>
</management-interfaces>
</management>
...
<interfaces>
<interface name="management">
<inet-address value="127.0.0.1"/>
</interface>
<interface name="public">
<inet-address value="127.0.0.1"/>
</interface>
</interfaces>
By default the native interface listens on port 9999 and the http interface listens on port 9990. The management interfaces are also associated with a network interface named 'management'. Although the configuration of this network interface by default matches the configuration of the 'public' interface it is recommended that these two configurations are not combined. Keeping them separate helps ensure that any changes to make the application server services more publicly visible don't inadvertently expose the management interfaces more publicly than is required.
The remaining sections in this chapter describe the security realm configuration in more detail - however if you would like to quickly enable a security realm and refine it for your requirements the default configuration contains a pre-defined realm definition based on a properties file and a script that can be executed using the command line interface to enable the security realm.
The security realms are defined within the <management> element of the standalone.xml or host.xml configurations. By default the following realm is defined:
<management>
<security-realms>
<security-realm name="PropertiesMgmtSecurityRealm">
<authentication>
<properties path="mgmt-users.properties" relative-to="jboss.server.config.dir" />
</authentication>
</security-realm>
</security-realms>
...
</management>
This default realm is used to authenticate the user connecting against a properties file called 'mgmt-users.properties' located in the same folder as the configuration. By default there are no users defined in the properties file so new users will need to be added in the format username=password.
To manually enable this realm the two interfaces can be configured to use this realm.
<management>
...
<management-interfaces>
<native-interface interface="management" port="9999" security-realm="PropertiesMgmtSecurityRealm" />
<http-interface interface="management" port="9990" security-realm="PropertiesMgmtSecurityRealm"/>
</management-interfaces>
</management>
This will enable HTTP Digest authentication for the HTTP interface and within the Native interface will also enable the Digest SASL mechanism - this means that for authentication the raw passwords are not transmitted from the client to the server.
To use the script to enable the realm first edit the 'mgmt-users.properties' script as the changes will take effect immediately so you will need at least one user defined and then execute one of the following commands.
For standalone server: -
./jboss-admin.sh --connect --file=scripts/secure-standalone-mgmt.cli
For a server in a managed domain: -
./jboss-admin.sh --connect --file=scripts/secure-host-controller-mgmt.cli
Please do be aware that this script is specifically written to run against a host called master which is the name in the default configuration. If additional hosts with unique names are created either the script should be updated or security manually applied in the new configuration. Also please note that the script only affects the named host it is run against; if there are multiple host controllers this script should be run against all of them with their correct names. Also please read the remainder of this chapter for information on how to configure the slave host controller to authenticate when connecting to the master host controller.
In addition to the above JBoss management protocols, remote JMX connectivity, which allows triggering JDK and application management operations. In order to secure an installation this service needs to be disabled by either removing the remote connector configuration, or removing the entire subsystem.
<subsystem xmlns="urn:jboss:domain:jmx:1.0">
<!-- Delete the following line to disable remote access -->
<jmx-connector registry-binding="jmx-connector-registry" server-binding="jmx-connector-server" />
</subsystem>
The configuration of the management interfaces happens within three elements inside the parent <management> element.
<management> <security-realms /> <outbound-connections /> <management-interfaces /> </management>
<security-realms /> - This is where one or more security realms can be configured to define how remote users connecting to this server will be authenticated and also to define the identity of the server.
<outbound-connections /> - Sometimes the configuration of the security realms will require a connection to an external resource; these connections are defined here.
<management-interfaces /> - This is where the HTTP interface and Native interfaces are defined as covered in the introduction.
The security configuration for the individual management interfaces is the simplest. All that is required for the interfaces is a 'security-realm' attribute with the name of the security realm to use. As the management interface starts it will query the capabilities of the security realm and enable the transport level security accordingly; e.g. the HTTP interface will attempt to use Digest authentication if the users passwords can be obtained from the security realm, and if the passwords can not be obtained from the security realm then the http interface will fallback to supporting Basic authentication.
<management> ...
<management-interfaces>
<native-interface ... security-realm="PropertiesMgmtSecurityRealm" />
<http-interface ... security-realm="PropertiesMgmtSecurityRealm"/>
</management-interfaces>
</management>
The management interfaces can be configured to use the same realm, however this is not required - if needed the different interfaces could be secured with different realms.
The <security-realms /> element is used to hold the definition of one or more security realms. The definition of a security realm follows the following structure.
<management>
<security-realms>
<security-realm name="SampleRealm">
<server-identities />
<authentication />
</security-realm>
</security-realms>
...
</management>
The <server-identities /> element defines how the server can identify itself. At the moment it is possible to configure a SSL identity to define how the server obtains it's identity from a keystore. It is also possible to configure a secret identity which is what secret or password the server uses when communicating with another server.
The <authentication /> element is used to define how users connecting to the server will be authenticated.
Initially three different mechanisms are supported for defining how the users connecting to the server are authenticated.
LDAP - Authentication is performed against an LDAP server to verify the users identity.
Users - The usernames and passwords of the users are defined within the domain model, this is only intended as a simple testing mechanism.
Properties - The usernames and passwords are defined in a properties file local to the server installation.
The following table outlines which mechanisms are compatible with which interface and the mechanism that will be used at the transport level to authenticate the end user.
|
Authentication |
HTTP |
Native |
|
LDAP |
HTTP BASIC |
SASL DIGEST |
|
Users |
HTTP DIGEST |
SASL DIGEST |
|
Properties |
HTTP DIGEST |
SASL DIGEST |
Please note that both the HTTP Basic and the SASL Plain mechanisms transmit the users password in a form that is easily reversed.
The following sections illustrate how each of these authentication mechanisms are configured.
The LDAP authenticator operates by first establishing a connection to the remote directory server. A search is then performed using the username supplied by the user to identify the fully qualified distinguished name of the user. Finally the authenticator establishes a new connection to the directory server, this time using the identified distinguished name along with the password supplied by the user; this verifies that the dn / password for the user is valid.
Here is a sample configuration showing a security realm with the LDAP authenticator defined.
<security-realm name="TestRealm">
<authentication>
<ldap connection="ldap_connection" base-dn="CN=Users,DC=mydomain,DC=aslab" username-attribute="sAMAccountName" />
</authentication>
</security-realm>
The following attributes can be specified on the ldap element: -
connection - The name of the connection defined in <outbound-connections> to use to connect to the LDAP directory.
base-dn - The distinguished name of the context to begin searching for the user.
username-attribute - The attribute of the user in the directory to match against the supplied username.
recursive (default - false) - Should the search recurs into sub-contexts or just search the specified context.
user-dn (default - dn) - The attribute of the user that holds the distinguished name, this is subsequently used to test authentication as the user can complete.
The Users authenticator is a simple authenticator to validate the user against usernames and password stored within the domain model. This authenticator is only intended for some very simple testing.
Here is a sample configuration showing a security realm with the Users authenticator defined: -
<security-realm name="TestRealm">
<authentication>
<users>
<user username="TestUser">
<password>TestUserPassword</password>
</user>
</users>
</authentication>
</security-realm>
Here each user is simply defined using the <user> element, the user name is specified using the 'username' attribute and the password is defined in a nested <password> element.
The Properties authenticator is very similar to the Users authenticator except that the usernames and passwords are now defined within a properties file. The benefit of this over the Users mechanism is that sensitive passwords are not leaking into the domain model.
Here is a sample configuration showing a security realm with the Properties authenticator defined:
<security-realm name="TestRealm">
<authentication>
<properties path="users.properties" relative-to="jboss.server.config.dir" />
</authentication>
</security-realm>
Here the properties file is simply specified where the 'path' attribute is the path to the file and the 'relative-to' attribute references a pre-defined path that the path attribute is relative to. In this example the users.properties can be found in the same folder as the standalone.xml file. If the 'relative-to' attribute is not specified, the value of the 'path' attribute must be an absolute path.
The <server-identities> element is used to define identities that the server uses to identify itself in various scenarios. Currently an SSL identity can be defined that is used to enable SSL on the HTTP interface and a Secret identity can be defined which holds a password that can be used when a host controller is establishing a connection to a remote domain controller.
The SSL identity currently takes configuration required to load a static keystore from the local filesystem. Later this will be enhanced to allow for different keystore types.
An example SSL definition is shown here: -
<security-realm name="TestRealm">
<server-identities>
<ssl>
<keystore path="server.keystore" relative-to="jboss.server.config.dir" password="keystore_password" />
</ssl>
</server-identities>
</security-realm>
The location of the actual keystore is defined in the same way the location of the properties file for the properties authenticator is defined with a path to the keystore and an optional relative-to attribute to make the path relative to a known location.
The Secret identity is used when a slave domain controller needs to establish a connection to a secured master domain controller.
To show this in context the following shows all the additional configuration on the slave domain controller:
<host xmlns="urn:jboss:domain:1.0"
name="slave">
<management>
<security-realms>
<security-realm name="TestRealm">
<server-identities>
<secret value="c2xhdmVfcGFzc3dvcmQ=" />
</server-identities>
</security-realm>
</security-realms>
...
</management>
<domain-controller>
<remote host="127.0.0.1" port="9999" security-realm="TestRealm" />
</domain-controller>
...
</host>
Here the <remote> definition for the domain controller references the defined security realm, this reference means that the specified security realm will be used to load the client side of the configuration (Later this will be expanded so the realm can also define SSL configuration for the client side of the connection).
The value specified for the secret is the password encoded using Base64. On attempting to connect to the remote domain controller the Base64 password will be decoded and the connection will authenticate using the name of the host (in this example 'slave') and the password obtained from the secret. The master domain controller will also need to be configured with a realm that contains the user 'slave' with the specified password.
Under the following issue AS7-1102 the password handling will be enhanced to allow better protection of configuration passwords from obfuscation using password based encryption through to encryption using external security providers, smart cards or hardware security modules over PKCS#11.
As described previously the outbound connections configuration is used to define connection to remote servers, presently only LDAP connections are supported but connection to databases will be added to allow for authentication using information stored in a databse.
The following configuration shows a sample connection definition to an LDAP server: -
<outbound-connections> <ldap name="ldap_connection" url="ldap://127.0.0.1" search-dn="CN=AS7 Test Server,CN=Users,DC=mydomain,DC=aslab" search-credential="AS_Password" /> </outboundconnections>
The following attributes can be set on the ldap element: -
name - The name to identify this connection, the ldap authenticator will use this name to reference the connection.
url - The URL to connect to the directory server.
search-dn - The distinguished name of the user to use to perform initial searches.
search-credential - The password of the user to connect for the search.
initial-context-factory (default - com.sun.jndi.ldap.LdapCtxFactory) - The initial context factory to use when establishing the connection.
The individual application servers establish a connection to the native interface exposed by their host controller - how are they authenticated?
Before the JBoss AS 7 process is created a random key is generated and passed to the application server instance that is started, the application server then uses this to authenticate when connecting to the native interface.