4.2. Setting up Client Authentication Between Servers and Agents

Authentication  is the process of verifying something's identity. With certificate-based authentication, an entity has to obtain a certificate file from a trusted source and, when initiating an SSL connection, that certificate is used to identify that entity. This ensures that the only parties involved in an SSL connection are who they say they are.
To set up certificate-based authentication for JBoss ON, several steps need to be taken. Encryption has to be enabled, certificates have to be issued and stored for the JBoss ON server and agents, and the servers and agents have to be configured to reject messages from untrusted clients.
SSL authentication for JBoss ON is bi-directional. The agents are configured to authenticate to the server, and then the server is configured to authentication to the agents.
Note
It is possible to configure one-way authentication, where only the server or only the agents have to authenticate. The best security is with bi-directional authentication, which is the configuration given here.
There are two transport methods in JBoss ON that allow SSL connections, sslservlet and sslsocket.
The procedure below uses sslsocket, which allows the default given port to be used for GUI connections while a special port is used for server-agent SSL connections.
Using sslservlet leverages the embedded Tomcat server, but this requires GUI users to authenticate to the server as well as enabling certificate-based authentication for agents.
To achieve this, you must add another web connector to the JON Server's Tomcat configuration that provides a secure but un-authenticated https connector for browsers to use.
Once you add this new web connector, users can connect their browsers to that connector's port (e.g. https://your-server-hostname:9443) in order to access the JON GUI using https without requiring certificate authentication.
This leaves the original secure Tomcat connector free to accept certificate-authenticated agent requests.
You can add such a web connector using the JBoss EAP CLI located at JBOSS_HOME/bin/jboss-cli.\[sh,bat].
For example, to add a new web connector on port 9443, you use the JBoss CLI first to create a new socket binding for that port 9443, then to create a new web connector using that new socket binding:

Procedure 4.1. (Optional) Adding a new tomcat web connector

  1. jboss-cli.sh --controller=127.0.0.1:6999 --connect --command='/socket-binding-group=standard-sockets/socket-binding=httpsbrowser/:add(port=9443)'
    
  2. jboss-cli.sh --controller=127.0.0.1:6999 --connect --command='/subsystem=web/connector=httpsbrowser/:add(socket-binding=httpsbrowser,scheme=https,protocol=HTTP/1.1,secure=true,enabled=true)'
    
  3. jboss-cli.sh  --controller=127.0.0.1:6999 --connect --command='/subsystem=web/connector=httpsbrowser/ssl=configuration:add(name=ssl,verify-client=false,key-alias=RHQ,password=${VAULT::restricted::rhq.server.tomcat.security.keystore.password::5fb458952ebdaa86aa0b4e8d3eac5d13},certificate-key-file=${jboss.server.config.dir}/rhq.keystore,certificate-file=${jboss.server.config.dir}/rhq.keystore'
    
  4. Restart the JBoss ON server
    rhqctl restart --server
    
Note
The above procedure creates the SSL configuration assuming you want to use the self-signed certificate found in JON's keystore. It is recommended that you use your own certificate, especially if you want one that is not self-signed. To use your own keystore's information, modify in the above procedure (specifically, the key-alias, password, certificate-key-file and certificate-file values).

Procedure 4.2. Setting up client authentication between servers and agents

  1. Enable encryption, as in Section 4.1, “Setting up Encryption”, only ensure that client authentication is not disabled.
  2. SSL socket connections will occur over a user-defined port. If necessary, open the firewall or VPN to allow access to that port.
  3. Generate SSL certificates for each JBoss ON server and agent. For example:
    keytool -genkey -dname "CN=server1.example.com"  -keystore server1-keystore.dat -validity 3650 -alias server1 -keyalg RSA -storetype JKS -keypass secret -storepass secret
    This creates a self-signed certificate with the following characteristics:
    • A common name (CN) value that is the same as the server hostname, server1.example.com. The -dname value must be the same as the hostname because during the initial steps of the SSL connection (the SSL handshake), the client will verify that the same identity which was issued the certificate is the same as the one presenting it. Meaning, it will match the hostname in the CN against the hostname of the server or agent presenting the certificate.
    • A keystore file called server1-keystore.dat
    • A validity period of 3650 days
    • An alias of server1
    • A key algorithm of RSA
    • Stored in the JKS format in the keystore
    • Key and storage passwords of secret
    Your organization may have a method already for generating or obtaining certificates. This example uses keytool; other utilities, like certutil, can be used as well. The keytool documentation is available through the Oracle-Sun site at http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html.
  4. Put each self-signed certificate in a single truststore file.
    1. Export the self-signed certificate from each keystore:
      keytool -export -keystore server1-keystore.dat -alias server1 -storetype JKS -storepass secret -file server1-cert
    2. Import every certificate into a single truststore file:
      keytool -import -keystore truststore.dat -alias server1 -storetype JKS -file server1-cert -noprompt -keypass secret -storepass secret
      -alias is the name to give to the imported certificate in the truststore. For convenience, this is the same as the alias of the original keystore file.
      Important
      Import every exported server and agent certificate into the same truststore file.
    3. Verify that all the certificates were successfully imported by using the keytool to list the certificates:
      keytool -list -keystore truststore.dat -storepass secret -storetype JKS
      									
      Keystore type: JKS
      Keystore provider: SUN
      									
      Your keystore contains 1 entries
      									
      server1, Feb 25, 2017, trustedCertEntry,
      Certificate fingerprint (MD5): 24:D9:8A:50:BA:1B:26:08:DC:44:A8:2A:9E:8A:43:D9
      
  5. Distribute both the keystore and the truststore files to all the JBoss ON and server and agent machines. Be sure to distribute the keystores only to the machines which match the hostname in the CN of the certificate; putting the keystore on the wrong machine will cause SSL connections to fail.
    1. For the server, copy the keystore (server1-keystore.dat) into the jon-server-version/jbossas/standalone/configuration/ directory of the JBoss AS server embedded in the JBoss Operations Network server. Rename server1-keystore.dat to keystore.dat.
    2. For the server, copy the truststore into the serverRoot/jon-server-3.3.0.GA/jbossas/standalone/configuration/ directory of the embedded JBoss AS server. Make sure this file is named truststore.dat.
    3. For the agent, copy the keystore into the agentRoot/rhq-agent/conf directory. Any certificate file in the agentRoot/rhq-agent/conf directory is retained even after an automatic update.
  6. Shut down the JBoss ON server.
    serverRoot/jon-server-3.3.0.GA/bin/rhqctl.sh stop
  7. Open the rhq-server.properties file for the JBoss ON server.
    vim serverRoot/jon-server-3.3.0.GA/bin/rhq-server.properties
  8. Enable client authentication when using sslsocket by setting the rhq.communications.connector.security.client-auth-mode parameter to need and the rhq.server.client.security.server-auth-mode-enabled parameter to true. When using sslservlet set rhq.server.tomcat.security.client-auth-mode parameter to true and the rhq.server.client.security.server-auth-mode-enabled parameter to true.
    Set the information about the keystore and truststore files.
    All of the configuration for incoming messages (agent-to-server communications when using sslsocket) is set in rhq.communications.connector.security.* parameters. The configuration for outgoing messages is set in rhq.server.client.security.* parameters.
    # Server-side SSL Security Configuration (for incoming messages from agents)
    # These are used when secure transports other than sslservlet are used
    rhq.communications.connector.security.secure-socket-protocol=TLS
    rhq.communications.connector.security.keystore.file=${jboss.server.config.dir}/keystore.dat
    rhq.communications.connector.security.keystore.algorithm=SunX509
    rhq.communications.connector.security.keystore.type=JKS
    rhq.communications.connector.security.keystore.password=secret
    rhq.communications.connector.security.keystore.key-password=secret
    rhq.communications.connector.security.keystore.alias=server1
    rhq.communications.connector.security.truststore.file=${jboss.server.config.dir}/truststore.dat
    rhq.communications.connector.security.truststore.algorithm=SunX509
    rhq.communications.connector.security.truststore.type=JKS
    rhq.communications.connector.security.truststore.password=secret
    rhq.communications.connector.security.client-auth-mode=need
    
    ...
    
    # Client-side SSL Security Configuration (for outgoing messages to agents)
    rhq.server.client.security.secure-socket-protocol=TLS
    rhq.server.client.security.keystore.file=${jboss.server.config.dir}/keystore.dat
    rhq.server.client.security.keystore.algorithm=SunX509
    rhq.server.client.security.keystore.type=JKS
    rhq.server.client.security.keystore.password=secret
    rhq.server.client.security.keystore.key-password=secret
    rhq.server.client.security.keystore.alias=server1
    rhq.server.client.security.truststore.file=${jboss.server.config.dir}/truststore.dat
    rhq.server.client.security.truststore.algorithm=SunX509
    rhq.server.client.security.truststore.type=JKS
    rhq.server.client.security.truststore.password=secret
    rhq.server.client.security.server-auth-mode-enabled=true
  9. Save the file and restart the server.
    serverRoot/jon-server-3.3.0.GA/bin/rhqctl start
  10. In the agent configuration file, uncomment the lines related to secure connections. These parameters begin with rhq.communications.connector.security.* and rhq.agent.client.security.* for agent-to-server communications and server-to-agent connections, respectively.
    Fill in the appropriate values.
    <entry key="rhq.communications.connector.security.secure-socket-protocol" value="TLS" />
    <entry key="rhq.communications.connector.security.keystore.file"          value="conf/keystore.dat" />
    <entry key="rhq.communications.connector.security.keystore.algorithm"     value="SunX509" />
    <entry key="rhq.communications.connector.security.keystore.type"          value="JKS" />
    <entry key="rhq.communications.connector.security.keystore.password"      value="rhqpwd" />
    <entry key="rhq.communications.connector.security.keystore.key-password"  value="rhqpwd" />
    <entry key="rhq.communications.connector.security.keystore.alias"         value="rhq" />
    <entry key="rhq.communications.connector.security.truststore.file"        value="conf/truststore.dat" />
    <entry key="rhq.communications.connector.security.truststore.algorithm"   value="SunX509" />
    <entry key="rhq.communications.connector.security.truststore.type"        value="JKS" />
    <entry key="rhq.communications.connector.security.truststore.password"    value="" />
    <entry key="rhq.communications.connector.security.client-auth-mode"       value="need" />
    
    <entry key="rhq.agent.client.security.secure-socket-protocol"   value="TLS" />
    <entry key="rhq.agent.client.security.keystore.file"            value="conf/keystore.dat" />
    <entry key="rhq.agent.client.security.keystore.algorithm"       value="SunX509" />
    <entry key="rhq.agent.client.security.keystore.type"            value="JKS" />
    <entry key="rhq.agent.client.security.keystore.password"        value="rhqpwd" />
    <entry key="rhq.agent.client.security.keystore.key-password"    value="rhqpwd" />
    <entry key="rhq.agent.client.security.keystore.alias"           value="rhq" />
    <entry key="rhq.agent.client.security.truststore.file"          value="conf/truststore.dat" />
    <entry key="rhq.agent.client.security.truststore.algorithm"     value="SunX509" />
    <entry key="rhq.agent.client.security.truststore.type"          value="JKS" />
    <entry key="rhq.agent.client.security.truststore.password"      value="" />
    <entry key="rhq.agent.client.security.server-auth-mode-enabled" value="true" />
    Note
    This shows how to edit the agent configuration by editing the agent configuration file. The agent configuration can also be edited by going through the advanced setup mode in the agent start script:
    agentRoot/rhq-agent/bin/rhq-agent.sh --cleanconfig --setup --advanced