Chapter 2. Securing a Managed Domain

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>

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>

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.

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>

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>