Menu Close

Chapter 2. Securing a Managed Domain

You can secure communication between a managed domain controller and its host controllers.

2.1. Configuring password authentication for the domain controller with elytron

You need to add a user to the master domain controller so that the slave controller can authenticate as the user. The slave controller attempts to authenticate at the HTTP interface of the master domain controller.

Procedure

  1. Add a user on the master domain controller. Use the add-user utility to add the user name, password, and other configurations. If the HTTP interface is secured with the ManagementRealm Elytron security realm, you must add a user to ManagementRealm.

    Note

    If you are using the default file based user and group authentication mechanism, run the EAP_HOME/bin/add-user.sh script.

    Note

    After you use the add-user utility to add user information, the server caches the contents of the properties files in memory. However, the server does check the modified time of the properties files on each authentication request and reloads if the time has been updated. This means that all changes made by the add-user utility are immediately applied to any running server.

    Note

    The default name of the realm for management users is ManagementRealm. When the add-user utility prompts for the realm name, you must accept the default realm name; that is, unless you have switched to a different realm.

  2. Add an authentication-configuration to the slave controller. The following example demonstrates adding a new authentication-configuration called slave with the user slave and the password1!:

    /host=slave/subsystem=elytron/authentication-configuration=slave:add(authentication-name=slave, credential-reference={clear-text=password1!})
  3. Add an authentication-context to the slave controller, as demonstrated in the following example:

    /host=slave/subsystem=elytron/authentication-context=slave-context:add(match-rules=[{authentication-configuration=slave}])
  4. Specify the domain controller location and authentication-context in the slave controller, as demonstrated in the following example:

    <domain-controller>
      <remote protocol="remote" host="localhost" port="9990" authentication-context="slave-context"/>
    </domain-controller>

Additional resources

  • For information about concepts and general configuration for the managed domain operating mode, see the Domain Management section of the JBoss EAP Configuration Guide.
  • For information about managing users, see the Management Users section of the JBoss EAP Configuration Guide.

2.2. Configuring password authentication for the domain controller with legacy core-management authentication

By default, Red Hat JBoss Enterprise Application Platform configures the master domain controller to require authentication from each slave controller that connects to the master domain controller.

Use the procedure to configure slave controllers with the proper credentials.

Procedure

  1. Use the add-user script to add a user to the master domain controller.

    1. Check that the user is added to the same realm the master uses to secure its management interface, which by default is ManagementRealm.
    2. Add a slave user, as demonstrated in the following example. Select yes for the Is this new user going to be used for one AS process to connect to another AS process? question.

      $ 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.4.0/standalone/configuration/mgmt-users.properties'
      Added user 'slave-user' to file '/home/user/EAP-7.4.0/domain/configuration/mgmt-users.properties'
      Added user 'slave-user' with groups  to file '/home/user/EAP-7.4.0/standalone/configuration/mgmt-groups.properties'
      Added user 'slave-user' with groups  to file '/home/user/EAP-7.4.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" />
      Important

      After adding the user, the script outputs a <secret> element. You need to use this element in the next step.

  2. Configure the slave controllers to use the credential. After you created the user on the master domain controller, you must update each slave controller to use that credential in the host configuration file. For example, host.xml or host-slave.xml.

    The following example shows the addition of the user name to the <remote> element in the domain controller configuration. Further the example shows the addition of the <secret> to the server-identities of the realm that is used to secure the <remote> element.

    Note

    Both the user name and <secret> were obtained by adding the user to the master domain controller in the previous step.

    ...
    <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:9990}"/>
          </discovery-options>
      </remote>
    </domain-controller>

Additional resources

  • For information about concepts and general configuration for the managed domain operating mode, see the Domain Management section of the JBoss EAP Configuration Guide.
  • For information about managing users, saee the Management Users section of the JBoss EAP Configuration Guide.

2.3. Configuring SSL or TLS for the domain controller with Elytron

You can configure JBoss EAP instances in a managed domain to use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) when communicating with each other, in other words, between the master domain controller and host controllers.

Important

When you configure SSL or 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 and domain controllers. For best results, set up two-way SSL or TLS between endpoints.

Prerequisites

  • Generated and configured all necessary certificates and keystores. To enable two-way SSL/TLS for the management interfaces, see either Enabling two-way SSL/TLS using a security command or Enabling two-way SSL/TLS using the Elytron subsystem commands.

    Note

    To set up two-way SSL or TLS between endpoints, you need to generate and configure certificates and keystores for the master domain controller and each host controller.

    Additionally, you must import the certificate of the master domain controller into each host controller keystore. Further, import each host controller certificate into the master domain controller keystore.

Procedure

  1. Add a user on the master domain controller. If you a re-using the default file based user and group authentication mechanism, run the EAP_HOME/bin/add-user.sh script. When prompted, add the username, password and other configurations.

    Note

    The default name of the realm for management users is ManagementRealm. When the add-user utility prompts for the realm name, you must accept the default realm name; that is, unless you have switched to a different realm.

    Note

    You must add a user on the master domain controller for the slave controller to authentication the user.

    Note

    The server caches the contents of the properties files in memory. However, the server does check the modified time of the properties files on each authentication request and reloads if the time has been updated. Therefore, any changes by the add-user utility are immediately applied to any running server.

  2. Configure the master domain controller to use SSL or TLS. The following example shows commands for configuring domain controller key-store, key-manager, trust-manager, and server-ssl-context for the server keystore and truststore.

    /host=master/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/server.keystore.jks,credential-reference={clear-text=secret},type=JKS)
    
    /host=master/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/server.truststore.jks,credential-reference={clear-text=secret},type=JKS)
    
    /host=master/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})
    
    /host=master/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)
    
    /host=master/subsystem=elytron/server-ssl-context=twoWaySSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM,want-client-auth=true,need-client-auth=true)
    
    /host=master/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context, value=twoWaySSC)
    Important

    Red Hat did not specify the algorithm attribute in the previous command, because the Elytron subsystem uses KeyManagerFactory.getDefaultAlgorithm() and TrustManagerFactory.getDefaultAlgorithm() to determine an algorithm by default. However, you can specify the algorithm attribute. To specify the algorithm attribute, you need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms.

    In the previous command you can specify SunX509 as the key manager algorithm attribute and PKIX as the trust manager algorithm attribute.

    Further, you need to determine what HTTPS protocols you want to support. The examples in this procedure use TLSv1.2.

    You can use the cipher-suite-filter to specify cipher suites, and the use-cipher-suites-order argument to honor server cipher suite order. The use-cipher-suites-order attribute by default is set to true. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.

  3. Configure an authentication context and domain controller location on each slave host controller. The following example configuration shows a domain controller that exists on localhost.

    Note

    You must specify the correct management user, password, and domain controller location for your environment.

    /host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:add()
    
    /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:add()
    
    /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=sasl-mechanism-selector,value=DIGEST-MD5)
    
    /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=authentication-name,value=slave)
    
    /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=realm,value=ManagementRealm)
    
    /host=slave1/subsystem=elytron/authentication-configuration=slaveHostSSLConfiguration:write-attribute(name=credential-reference,value={clear-text=password1!})
    
    /host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:write-attribute(name=match-rules,value=[{match-host=localhost,authentication-configuration=slaveHostSSLConfiguration}]
    
    /host=slave1:write-remote-domain-controller(host=localhost,port=9990,protocol=remote,authentication-context=slaveHostSSLContext)
  4. Configure each slave host controller to use SSL or TLS. The following commands configure the slave host controller key-store, key-manager, trust-manager, client-ssl-context, and authentication-context for the server keystore and truststore. Further, the example shows a domain controller that exists on localhost.

    Note

    You must specify the correct domain controller location for your environment.

    /host=slave1/subsystem=elytron/key-store=twoWayKS:add(path=/path/to/client.keystore.jks,credential-reference={clear-text=secret},type=JKS)
    
    /host=slave1/subsystem=elytron/key-store=twoWayTS:add(path=/path/to/client.truststore.jks,credential-reference={clear-text=secret},type=JKS)
    
    /host=slave1/subsystem=elytron/key-manager=twoWayKM:add(key-store=twoWayKS,credential-reference={clear-text=secret})
    
    /host=slave1/subsystem=elytron/trust-manager=twoWayTM:add(key-store=twoWayTS)
    
    /host=slave1/subsystem=elytron/client-ssl-context=twoWayCSC:add(key-manager=twoWayKM,protocols=["TLSv1.2"],trust-manager=twoWayTM)
    
    /host=slave1/subsystem=elytron/authentication-context=slaveHostSSLContext:write-attribute(name=match-rules,value=[{match-host=localhost,authentication-configuration=slaveHostSSLConfiguration,ssl-context=twoWayCSC}])
    Important

    Red Hat did not specify the algorithm attribute in the previous command, because the Elytron subsystem uses KeyManagerFactory.getDefaultAlgorithm() and TrustManagerFactory.getDefaultAlgorithm() to determine an algorithm by default. However, you can specify the algorithm attribute. To specify the algorithm attribute, you need to know what key manager algorithms are provided by the JDK you are using. For example, a JDK that uses SunJSSE provides the PKIX and SunX509 algorithms.

    In the previous command you can specify SunX509 as the key manager algorithm attribute and PKIX as the trust manager algorithm attribute.

    Further, you need to determine what HTTPS protocols you want to support. The examples in this procedure use TLSv1.2.

    You can use the cipher-suite-filter to specify cipher suites, and the use-cipher-suites-order argument to honor server cipher suite order. The use-cipher-suites-order attribute by default is set to true. This differs from the legacy security subsystem behavior, which defaults to honoring client cipher suite order.

  5. Reload all the JBoss EAP hosts in your managed domain.

Additional resources

  • For information about concepts and general configuration for the managed domain operating mode, see the Domain Management section of the JBoss EAP Configuration Guide.
  • For information about managing users, saee the Management Users section of the JBoss EAP Configuration Guide.

2.4. Configuring SSL in domain mode by using Elytron

In JBoss EAP 7.1 or later versions, you can use Elytron to configure SSL in domain mode.

Prerequisites

  • JBoss EAP 7.1 or later.
  • Elytron

Procedure

  1. Create a self-signed certificate to enable SSL:

    keytool -genkey -alias jboss -keysize 2048 -validity 365 -keyalg RSA -sigalg SHA256withRSA -keystore jboss.jks -storepass jboss@123 -keypass jboss@123 -dname "CN=example.com, OU=JavaEE, O=Red Hat, C=IN"
  2. Create a keystore, a key-manager and an ssl-context using the management CLI.

    #Configure a keystore
    /profile=<profile-name>/subsystem=elytron/key-store=httpsKS:add(path="${jboss.home.dir}/ssl/jboss.jks", credential-reference={clear-text=jboss@123}, type=JKS)
    
    #Create a new key-manager
    /profile=<profile-name>/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,algorithm="SunX509",credential-reference={clear-text=jboss@123})
    
    #Configure new server-ssl-context reference with protocol and ciphers
    /profile=<profile-name>/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])
  3. Configure the undertow subsystem to map the Elytron ssl-context:

    batch
    /profile=<profile-name>/subsystem=undertow/server=default-server/https-listener=https:undefine-attribute(name=security-realm)
    /profile=<profile-name>/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context,value=httpsSSC)
    run-batch
  4. Optional: Secure the management-interface to use the same ssl-context:

    The host-*.xml files define the configuration for the domain controllers and host controllers, which hold the management interfaces. To ensure that SSL is configured successfully, you must define the ssl-context again on the host.

    #Configure a keystore on the master DC host
    /host=<host-name>/subsystem=elytron/key-store=httpsKS:add(path="${jboss.home.dir}/ssl/jboss.jks", credential-reference={clear-text=jboss@123}, type=JKS)
    
    #Create a new key-manager on the master DC host
    /host=<host-name>/subsystem=elytron/key-manager=httpsKM:add(key-store=httpsKS,algorithm="SunX509",credential-reference={clear-text=jboss@123})
    
    #Configure new server-ssl-context reference with protocol and ciphers on the master DC host
    /host=<host-name>/subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=httpsKM,protocols=["TLSv1.2"])
    
    #Configure the secure-port and ssl-context for management-http interface  on the master DC host
    /host=<host-name>/core-service=management/management-interface=http-interface:write-attribute(name=ssl-context,value=httpsSSC)
    
    /host=<host-name>/core-service=management/management-interface=http-interface:write-attribute(name=secure-port,value=9993)
  5. Ensure that a truststore is properly configured to enable the remote host controllers to connect to the domain controller through SSL. For more information, see Configuring SSL/TLS Between Domain and Host Controllers Using Elytron.
  6. Reload the servers to ensure that the changes are effective:

    reload --host=<host-name>

Verification

  • Verify the TLS connection by using a browser or openSSL on the Red Hat Enterprise Linux command line:

    openssl s_client -connect host:8443

    The output displays information about the certificate and the TLS version used.

    SSL-Session:
    Protocol: TLSv1.2

2.5. Configuring SSL or TLS for the legacy core management authentication mechanism

You can configure JBoss EAP instances in a managed domain to use Secure Sockets Layer (SSL) or Transport Layer Security (TLS) when communicating with each other, in other words, between the master domain controller and host controllers.

Important

When you configure SSL or 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 and domain controllers. For best results, set up two-way SSL or TLS between endpoints.

Prerequisites

  • Generated and configured all necessary certificates and keystores. To enable two-way SSL/TLS for the management interfaces, see Setting up two-way SSL/TLS for the management interfaces with legacy core management authentication.

    Note

    To set up two-way SSL or TLS between endpoints, you need to generate and configure certificates and keystores for the master domain controller and each host controller.

    Additionally, you must import the certificate of the master domain controller into each host controller keystore. Further, import each host controller certificate into the master domain controller keystore.

Procedure

  1. Configure the master domain controller to use SSL or TLS as demonstrated in the following example. When you have configured all the certificates and the keystores, you need to configure a security realm to use two-way SSL/TLS. You can achieve this by configuring a security realm to use SSL/TLS. The configured security realm secures the management interface used for connecting between host controllers and the master domain controller.

    Note

    Run the following commands in either batch mode or on the server. You must reload the server after adding the ssl server identity. The example in this procedure is run in 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=http-interface:write-attribute(name=security-realm,value=CertificateRealm)
    
    run-batch
  2. Configure all host controllers to use SSL or TLS, as demonstrated in the following example:

    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=http-interface:write-attribute(name=security-realm,value=CertificateRealm)
    
    run-batch
  3. Update the security realm that is used when connecting the master domain controller. You must make this update to the host controller configuration file whilst the server is not running. For example, host.xml or host-slave.xml.

    <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:9990}"/>
        </discovery-options>
      </remote>
    </domain-controller>

Additional resources