Chapter 3. Securing a Managed Domain

In addition to securing the management interfaces, you can also secure communication between JBoss EAP instances in a managed domain.

For information on concepts and general configuration for the managed domain operating mode, see the Domain Management section of the JBoss EAP Configuration Guide.

3.1. Configure Password Authentication Between Slaves and the Domain Controller

When configuring a managed domain, by default, the master domain controller is configured to require authentication for each slave controller that connects to it. To configure slave controllers with the proper credentials, you must do the following:

  1. Add a user to the master domain controller

    You need to add a user to the master domain controller using the add-user script. Specifically, you will need to ensure that the user is added to the same realm the master uses to secure its management interface, which by default is ManagementRealm. You also need to ensure you answer yes to the Is this new user going to be used for one AS process to connect to another AS process? question.

    Important

    After adding the user, the script will output a <secret> element, which will be used in the next step. You must keep this value for use in the next step.

    Example Adding a Slave User

    $ EAP_HOME/bin/add-user.sh
    
    What type of user do you wish to add?
     a) Management User (mgmt-users.properties)
     b) Application User (application-users.properties)
    (a): a
    
    Enter the details of the new user to add.
    Using realm 'ManagementRealm' as discovered from the existing property files.
    Username : slave-user
    Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file.
     - The password should be different from the username
     - The password should not be one of the following restricted values {root, admin, administrator}
     - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
    Password :
    Re-enter Password :
    What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[  ]:
    About to add user 'slave-user' for realm 'ManagementRealm'
    Is this correct yes/no? yes
    Added user 'slave-user' to file '/home/user/EAP-7.0.0/jboss-eap-7.0/standalone/configuration/mgmt-users.properties'
    Added user 'slave-user' to file '/home/user/EAP-7.0.0/jboss-eap-7.0/domain/configuration/mgmt-users.properties'
    Added user 'slave-user' with groups  to file '/home/user/EAP-7.0.0/jboss-eap-7.0/standalone/configuration/mgmt-groups.properties'
    Added user 'slave-user' with groups  to file '/home/user/EAP-7.0.0/jboss-eap-7.0/domain/configuration/mgmt-groups.properties'
    Is this new user going to be used for one AS process to connect to another AS process?
    e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server EJB calls.
    yes/no? yes
    To represent the user add the following to the server-identities definition <secret value="ABCzc3dv11Qx" />

  2. Configure the slave controllers to use the credential.

    Once you have created the user on the master domain controller, you will need to update each slave controller to use that credential in the host configuration file, for example host.xml or host-slave.xml. To do so, you need to add the username to the <remote> element in the domain controller configuration. You will also need to add the <secret> to the server identities of the realm used to secure the <remote> element. Both the username and <secret> were obtained when adding the user to the master domain controller in the previous step.

    Example

    ...
    <security-realm name="ManagementRealm">
        <server-identities>
            <!-- Replace this with either a base64 password of your own, or use a vault with a vault expression -->
            <secret value="ABCzc3dv11Qx"/>
        </server-identities>
    ...
    <domain-controller>
      <remote security-realm="ManagementRealm" username="slave-user">
          <discovery-options>
              <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/>
          </discovery-options>
      </remote>
    </domain-controller>

3.2. Configuring SSL/TLS Between Domain and Host Controllers

Important

When you configure SSL/TLS to be used between JBoss EAP instances in a managed domain, each instance can have a client or server role depending on the interaction. This includes all host controllers as well as domain controllers. As a result, it is recommended that you setup two-way SSL/TLS between endpoints.

You can configure JBoss EAP instances in a managed domain to use SSL/TLS when communicating with each other, in other words, between the master domain controller and host controllers. To do so, you will need to do the following:

  1. Generate and configure all necessary certificates and keystores.

    In order to set up two-way SSL/TLS between endpoints, you need to generate and configure certificates and keystores for the master domain controller as well as each host controller. You also need to import the certificate of the master domain controller into each host controller’s keystore as well as import each host controller’s certificate into the master domain controller’s keystore. The specifics of this process is covered in a Setting up Two-Way SSL/TLS for the Management Interfaces.

  2. Configure the master domain controller to use SSL/TLS.

    Once you have configured all certificates and keystores, you need to configure a security realm to use two-way SSL/TLS. This is done by configuring a security realm to use SSL/TLS and to require it for authentication. That security realm is then used to secure the management interface used for connecting between host controllers and the master domain controller.

    Note

    The following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode.

    batch
    
    /host=master/core-service=management/security-realm=CertificateRealm:add()
    
    /host=master/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(alias=domaincontroller,keystore-relative-to=jboss.domain.config.dir,keystore-path=domaincontroller.jks,keystore-password=secret)
    
    /host=master/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-relative-to=jboss.domain.config.dir,keystore-path=domaincontroller.jks,keystore-password=secret)
    
    /host=master/core-service=management/security-realm=CertificateRealm/authentication=local:add(default-user=\$local)
    
    /host=master/core-service=management/security-realm=CertificateRealm/authentication=properties:add(relative-to=jboss.domain.config.dir,path=mgmt-users.properties)
    
    /host=master/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm)
    
    run-batch
  3. Configure all host controllers to use SSL/TLS.

    Once you have the master domain controller configured to use two-way SSL/TLS, you need to configure each host controller to use it as well. The process is very much the same as the master domain controller configuration, except you will need to use the keystore specific to each host.

    Note

    The following commands below must either be run in batch mode, or the server must be reloaded after adding the ssl server identity. The example below is shown using batch mode.

    batch
    
    /host=instance1/core-service=management/security-realm=CertificateRealm:add()
    
    /host=instance1/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(alias=instance1,keystore-relative-to=jboss.domain.config.dir,keystore-path=instance1.jks,keystore-password=secret)
    
    /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-relative-to=jboss.domain.config.dir,keystore-path=instance1.jks,keystore-password=secret)
    
    /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=local:add(default-user="\$local")
    
    /host=instance1/core-service=management/security-realm=CertificateRealm/authentication=properties:add(relative-to=jboss.domain.config.dir,path=mgmt-users.properties)
    
    /host=instance1/core-service=management/management-interface=native-interface:write-attribute(name=security-realm,value=CertificateRealm)
    
    run-batch

    Additionally, you will need to update the security realm used when connecting the master domain controller. This change must be done directly in the host controller’s configuration file, e.g. host.xml or host-slave.xml, while the server is not running.

    Example Host Controller Configuration File

    <domain-controller>
            <remote security-realm="CertificateRealm" username="slave-user">
                <discovery-options>
                    <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9999}"/>
                </discovery-options>
            </remote>
        </domain-controller>

    Warning

    Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.