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
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 theManagementRealm
Elytron security realm, you must add a user toManagementRealm
.NoteIf you are using the default file based user and group authentication mechanism, run the
EAP_HOME/bin/add-user.sh
script.NoteAfter 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 theadd-user
utility are immediately applied to any running server.NoteThe default name of the realm for management users is
ManagementRealm
. When theadd-user
utility prompts for the realm name, you must accept the default realm name; that is, unless you have switched to a different realm.Add an
authentication-configuration
to the slave controller. The following example demonstrates adding a newauthentication-configuration
calledslave
with the userslave
and thepassword1!
:/host=slave/subsystem=elytron/authentication-configuration=slave:add(authentication-name=slave, credential-reference={clear-text=password1!})
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}])
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
Use the
add-user
script to add a user to the master domain controller.-
Check that the user is added to the same realm the master uses to secure its management interface, which by default is
ManagementRealm
. 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" />
ImportantAfter adding the user, the script outputs a
<secret>
element. You need to use this element in the next step.
-
Check that the user is added to the same realm the master uses to secure its management interface, which by default is
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
orhost-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 theserver-identities
of the realm that is used to secure the<remote>
element.NoteBoth 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.
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.
NoteTo 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
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.NoteThe default name of the realm for management users is
ManagementRealm
. When theadd-user
utility prompts for the realm name, you must accept the default realm name; that is, unless you have switched to a different realm.NoteYou must add a user on the master domain controller for the slave controller to authentication the user.
NoteThe 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.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
, andserver-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)
ImportantRed Hat did not specify the algorithm attribute in the previous command, because the Elytron subsystem uses
KeyManagerFactory.getDefaultAlgorithm()
andTrustManagerFactory.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 thePKIX
andSunX509
algorithms.In the previous command you can specify
SunX509
as the key manager algorithm attribute andPKIX
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 theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.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
.NoteYou 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)
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
, andauthentication-context
for the server keystore and truststore. Further, the example shows a domain controller that exists onlocalhost
.NoteYou 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}])
ImportantRed Hat did not specify the algorithm attribute in the previous command, because the Elytron subsystem uses
KeyManagerFactory.getDefaultAlgorithm()
andTrustManagerFactory.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 thePKIX
andSunX509
algorithms.In the previous command you can specify
SunX509
as the key manager algorithm attribute andPKIX
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 theuse-cipher-suites-order
argument to honor server cipher suite order. Theuse-cipher-suites-order
attribute by default is set totrue
. This differs from the legacysecurity
subsystem behavior, which defaults to honoring client cipher suite order.- 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
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"
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"])
Configure the
undertow
subsystem to map the Elytronssl-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
Optional: Secure the
management-interface
to use the samessl-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 thessl-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)
- 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.
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.
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.
NoteTo 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
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.
NoteRun 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
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
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
orhost-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
- 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 the process of setting up a two-way SSL or TLS, see Setting up Two-way SSL/TLS for the Management Interfaces with Legacy Core Management Authentication in the How to Configure Server Security guide.