Chapter 2. Securing the Server and Its Interfaces

Create a keystore to secure the management interfaces.

Use the following to generate a keystore, replacing the example values for the parameters, for example alias, keypass, keystore, storepass and dname, with the correct values for the environment.

$ keytool -genkeypair -alias appserver -storetype jks -keyalg RSA -keysize 2048 -keypass password1 -keystore EAP_HOME/standalone/configuration/identity.jks -storepass password1 -dname "CN=appserver,OU=Sales,O=Systems Inc,L=Raleigh,ST=NC,C=US" -validity 730 -v

Ensure the management interfaces bind to HTTPS.

Optional: Use custom socket-binding-group. If you want to use a custom socket-binding-group, you must ensure the management-https binding is defined, which by default is bound to port 9993. You can verify this by reviewing the socket-binding-group section of the server’s configuration file or by using the management CLI:

/socket-binding-group=standard-sockets/socket-binding=management-https:read-resource(recursive=true)

{
    "outcome" => "success",
    "result" => {
        "client-mappings" => undefined,
        "fixed-port" => false,
        "interface" => "management",
        "multicast-address" => undefined,
        "multicast-port" => undefined,
        "name" => "management-https",
        "port" => expression "${jboss.management.https.port:9993}"
    }
}

Create a new security realm. In this example, the new security realm using HTTPS, ManagementRealmHTTPS, uses a properties file named https-mgmt-users.properties located in the EAP_HOME/standalone/configuration/ directory for storing usernames and passwords. Usernames and passwords can be added to the file later, but for now, you need to create an empty file named https-mgmt-users.properties and save it to that location. The below example shows using the touch command, but you may also use other mechanisms, such as a text editor.

$ touch EAP_HOME/standalone/configuration/https-mgmt-users.properties

Next, enter the following CLI commands to create a new security realm named ManagementRealmHTTPS:

/core-service=management/security-realm=ManagementRealmHTTPS:add

/core-service=management/security-realm=ManagementRealmHTTPS/authentication=properties:add(path=https-mgmt-users.properties,relative-to=jboss.server.config.dir)

At this point, you have created a new security realm and configured it to use a properties file for authentication. You must now add users to that properties file using the add-user script, which is available in the EAP_HOME/bin/ directory. When running the add-user script, you must specify both the properties file and the security realm using the -up and -r options respectively. From there, the add-user script will interactively prompt you for the username and password information to store in the https-mgmt-users.properties file.

$ EAP_HOME/bin/add-user.sh -up EAP_HOME/standalone/configuration/https-mgmt-users.properties -r ManagementRealmHTTPS
...
Enter the details of the new user to add.
Using realm 'ManagementRealmHTTPS' as specified on the command line.
...
Username : httpUser
Password requirements are listed below. To modify these restrictions edit the add-user.properties configuration file.
 - The password must not be one of the following restricted values {root, admin, administrator}
 - The password must contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s)
 - The password must be different from the username
...
Password :
Re-enter Password :
About to add user 'httpUser' for realm 'ManagementRealmHTTPS'
...
Is this correct yes/no? yes
..
Added user 'httpUser' to file 'EAP_HOME/configuration/https-mgmt-users.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? no

Configure the management interfaces to use the new security realm.

/core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=ManagementRealmHTTPS)

Configure the management interfaces to use the keystore.

Use the below CLI command to configure the management interfaces to use the keystore. For the parameters file, password and alias their values must be copied from the first step.

/core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:add(keystore-path=identity.jks,keystore-relative-to=jboss.server.config.dir,keystore-password=password1, alias=appserver)

/core-service=management/security-realm=ManagementRealmHTTPS/server-identity=ssl:write-attribute(name=keystore-password,value=newpassword)

At this point, you need to reload the server’s configuration:

reload

After reloading the server configuration, the log should contain the following, just before the text which states the number of services that are started:

13:50:54,160 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0061: Http management interface listening on https://127.0.0.1:9993/management
13:50:54,162 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0052: Admin console listening on https://127.0.0.1:9993

The management interfaces are now listening on port 9993, which confirms that the procedure was successful.

Update the jboss-cli.xml.

If using the management CLI to perform management actions, the following changes must to be made to the EAP_HOME/bin/jboss-cli.xml file:

Generate the keystores.

$ keytool -genkeypair -alias HOST1_alias -keyalg RSA -keysize 1024 -validity 365 -keystore HOST1.keystore.jks -dname "CA_HOST1" -keypass secret -storepass secret

$ keytool -genkeypair -alias HOST2_alias -keyalg RSA -keysize 1024 -validity 365 -keystore HOST2.keystore.jks -dname "CA_HOST2" -keypass secret -storepass secret

Export the certificates.

$ keytool -exportcert  -keystore HOST1.keystore.jks -alias HOST1_alias -keypass secret -storepass secret -file HOST1.cer

$ keytool -exportcert  -keystore HOST2.keystore.jks -alias HOST2_alias -keypass secret -storepass secret -file HOST2.cer

Import the certificates into the opposing truststores.

$ keytool -importcert -keystore HOST1.truststore.jks -storepass secret -alias HOST2_alias -trustcacerts -file HOST2.cer

$ keytool -importcert -keystore HOST2.truststore.jks -storepass secret -alias HOST1_alias -trustcacerts -file HOST1.cer

Define a CertificateRealm.

Define a CertificateRealm in the configuration for the server (host.xml or standalone.xml) and point the interface to it. This can be done using the following commands:

/core-service=management/security-realm=CertificateRealm:add()

/core-service=management/security-realm=CertificateRealm/server-identity=ssl:add(keystore-path=/path/to/HOST1.keystore.jks, keystore-password=secret,alias=HOST1_alias)

/core-service=management/security-realm=CertificateRealm/authentication=truststore:add(keystore-path=/path/to/HOST1.truststore.jks,keystore-password=secret)

Change the security-realm of the http-interface to the new CertificateRealm.

/core-service=management/management-interface=http-interface:write-attribute(name=security-realm,value=CertificateRealm)

Add the SSL/TLS configuration for the CLI.

Add the SSL/TLS configuration for the CLI, which uses EAP_HOME/bin/jboss-cli.xml as a settings file.

To store the keystore and truststore passwords in plain text, edit EAP_HOME/bin/jboss-cli.xml and add the SSL/TLS configuration using the appropriate values for the variables:

<ssl>
  <alias>HOST2_alias</alias>
  <key-store>/path/to/HOST2.keystore.jks</key-store>
  <key-store-password>secret</key-store-password>
  <trust-store>/path/to/HOST2.truststore.jks</trust-store>
  <trust-store-password>secret</trust-store-password>
  <modify-trust-store>true</modify-trust-store>
</ssl>

To use the keystore and truststore passwords stored in a password vault, you need to add the vault configuration and appropriate vault values to EAP_HOME/bin/jboss-cli.xml:

<ssl>
  <vault>
    <vault-option name="KEYSTORE_URL" value="path-to/vault/vault.keystore"/>
    <vault-option name="KEYSTORE_PASSWORD" value="MASK-5WNXs8oEbrs"/>
    <vault-option name="KEYSTORE_ALIAS" value="vault"/>
    <vault-option name="SALT" value="12345678"/>
    <vault-option name="ITERATION_COUNT" value="50"/>
    <vault-option name="ENC_FILE_DIR" value="EAP_HOME/vault/"/>
  </vault>
  <alias>HOST2_alias</alias>
  <key-store>/path/to/HOST2.keystore.jks</key-store>
  <key-store-password>VAULT::VB::cli_pass::1</key-store-password>
  <key-password>VAULT::VB::cli_pass::1</key-password>
  <trust-store>/path/to/HOST2.truststore.jks</trust-store>
  <trust-store-password>VAULT::VB::cli_pass::1</trust-store-password>
  <modify-trust-store>true</modify-trust-store>
</ssl>

Add and configure an HTTPS security realm first. Once the HTTPS security realm has been configured, configure an https-listener in the undertow subsystem that references the security realm:

batch

/core-service=management/security-realm=HTTPSRealm/:add

/core-service=management/security-realm=HTTPSRealm/server-identity= \
ssl:add(keystore-path=identity.jks, \
keystore-relative-to=jboss.server.config.dir, \
keystore-password=password1, alias=appserver)

/subsystem=undertow/server=default-server/https-listener=https:add( \
socket-binding=https, security-realm=HTTPSRealm)

run-batch

Reload the server for the changes to take effect.

reload

Create an SSL/TLS security realm on the master domain controller.

You need to create an SSL/TLS security realm on the master domain controller configured to use your NSS database as a PKCS11 provider.

<security-realm name="HTTPSRealm">
    <server-identities>
        <ssl>
            <engine enabled-protocols="TLSv1.1"/>
            <keystore provider="PKCS11" keystore-password="strongP@ssword1"/>
        </ssl>
    </server-identities>
    <authentication>
        <local default-user="\$local"/>
        <properties path="https-users.properties" relative-to="jboss.domain.config.dir"/>
    </authentication>
</security-realm>

Create an SSL/TLS security realm on each host controller.

You need to create a security realm with an SSL/TLS truststore for authentication.

<security-realm name="HTTPSRealm">
  <authentication>
    <truststore provider="PKCS11" keystore-password="strongP@ssword1"/>
  </authentication>
</security-realm>

Secure the native interface on the master domain controller.

You need to ensure that the native interface on the master domain controller is secured with the security realm you just created.

<management-interfaces>
  ...
  <native-interface security-realm="HTTPSRealm">
    <socket interface="management" port="${jboss.management.native.port:9999}"/>
   </native-interface>
</management-interfaces>

Use the SSL/TLS realm on each host controller to connect to the master domain controller.

You need to update the security realm used for connecting to the master domain controller. This change must be done directly in the host controller’s configuration file, for example host.xml or host-slave.xml, while the server is not running.

<domain-controller>
  <remote security-realm="HTTPSRealm">
    <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>

Update how each server connects back to its host controller.

You also need to update how each server connects back to its host controller.

<server name="my-server" group="my-server-group">
  <ssl ssl-protocol="TLS" trust-manager-algorithm="SunX509" truststore-type="PKCS11" truststore-password="strongP@ssword1"/>
</server>

Configure two-way SSL/TLS in a managed domain.

To enable two-way SSL/TLS, add a truststore authentication method to the SSL/TLS security realm for the master domain controller, execute the following management CLI commands:

/host=master/core-service=management/security-realm=HTTPSRealm/authentication=truststore:add(keystore-provider="PKCS11",keystore-password="strongP@ssword1")

reload --host=master

You also need to update each host controller’s security realm to have an SSL server identity, execute the following management CLI commands:

/host=host1/core-service=management/security-realm=HTTPSRealm/server-identity=ssl:add(keystore-provider=PKCS11, keystore-password="strongP@ssword1",enabled-protocols=["TLSv1.1"])

reload --host=host1

Create a security domain.

In this example, a security domain is created with the UserRoles login module, but other login modules may be used as well:

/subsystem=security/security-domain=UsersLMDomain:add(cache-type=default)

/subsystem=security/security-domain=UsersLMDomain/authentication=classic:add

/subsystem=security/security-domain=UsersLMDomain/authentication=classic/login-module=UsersRoles:add(code=UsersRoles, flag=required,module-options=[("usersProperties"=>"users.properties"),("rolesProperties"=>"roles.properties")])

Create a security realm with JAAS authentication.

/core-service=management/security-realm=SecurityDomainAuthnRealm:add

/core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:add(name=UsersLMDomain)

Update the http-interface management interface to use new security realm.

/core-service=management/management-interface=http-interface/:write-attribute(name=security-realm,value=SecurityDomainAuthnRealm)

Optional: Assign group membership.

The attribute assign-groups determines whether loaded user membership information from the security domain is used for group assignment in the security realm. When set to true, this group assignment is used for Role-Based Access Control (RBAC).

/core-service=management/security-realm=SecurityDomainAuthnRealm/authentication=jaas:write-attribute(name=assign-groups,value=true)

Open the security domain’s detailed view.

Navigate to the Auditing configuration.

Click on Audit at the left side of the screen.

The configuration area is divided into two areas: Provider Modules and Details. The provider module is the basic unit of configuration. A security domain can include several provider modules each of which can include attributes and options.

Add a provider module.

Click Add and fill in the Code section with the classname of the provider module. Also fill in the Name section with the desired name.

Verify the module is working.

The goal of an audit module is to provide a way to monitor the events in the security subsystem. This monitoring can be done by means of writing to a log file, email notifications, or any other measurable auditing mechanism.

For example, JBoss EAP includes the org.jboss.security.audit.providers.LogAuditProvider module by default. If enabled following the steps above , this audit module writes security notifications to a audit.log file in the log subfolder within the EAP_HOME directory.

To verify if the steps above have worked in the context of the org.jboss.security.audit.providers.LogAuditProvider, perform an action that is likely to trigger a notification and then check the audit log file.

Optional: Add, edit, or remove module options.

To add options to your module, click its entry in the Modules list, and select the Module Options tab in the Details section of the page. Click Add, and provide the key and value for the option.

To edit an option that already exists, click Remove to remove it, and click Add to add it again with the correct options.