README.adoc

../shared-doc/attributes.adoc

helloworld-ssl: {productName} Server Side SSL Configuration Example

The helloworld-ssl quickstart is a basic example that demonstrates server side SSL configuration in {productName}.

What is it?

This helloworld-ssl quickstart demonstrates the configuration of SSL in {productNameFull}.

This quickstart shows how to configure {productName} to enable TLS/SSL configuration for the new undertow web subsystem.

Before you run this example, you must create certificates and configure the server to use SSL.

../shared-doc/system-requirements.adoc ../shared-doc/use-of-jboss-home-name.adoc

Generate a Keystore and Self-signed Certificate

1. Open a terminal and navigate to the {productName} server configuration directory:

   $ cd {jbossHomeName}/standalone/configuration/

2. Create a certificate for your server using the following command:

   $>keytool -genkey -alias mycert -keyalg RSA -sigalg MD5withRSA -keystore server.keystore -storepass secret -keypass secret -validity 9999
   
   What is your first and last name?
      [Unknown]:  localhost
   What is the name of your organizational unit?
      [Unknown]:  wildfly
   What is the name of your organization?
      [Unknown]:  jboss
   What is the name of your City or Locality?
      [Unknown]:  Raleigh
   What is the name of your State or Province?
      [Unknown]:  Carolina
   What is the two-letter country code for this unit?
      [Unknown]:  US
   Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct?
      [no]:  yes

   Make sure you enter your desired "hostname" for the first and last name field, otherwise you might run into issues while permanently accepting this certificate as an exception in some browsers. Chrome does not currently exhibit this issue.

../shared-doc/back-up-server-standalone-configuration.adoc ../shared-doc/start-the-standalone-server.adoc

Configure the Server

You configure the SSL context by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a configure-ssl.cli script provided in the root directory of this quickstart.

1. Before you begin, make sure you do the following:

   • Back up the {productName} standalone server configuration as described above.

   • Start the {productName} server with the standalone default profile as described above.

2. Review the configure-ssl.cli file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands.

3. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server:

   $ {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-ssl.cli

   Note	For Windows, use the {jbossHomeName}\bin\jboss-cli.bat script.

   You should see the following result when you run the script:

   The batch executed successfully
   process-state: reload-required

Test the Server SSL Configuration

To test the connection to the SSL port of your your server instance by opening a browser and navigation to https://localhost:8443/. Note, that you get the privacy error because the server certificate is self-signed. If you need to use a fully signed certificate, you must get a PEM file from the Certificate Authority and then import the PEM into the keystore. . Stop the {productName} server.

Review the Modified Server Configuration

1. Stop the server and open the {jbossHomeName}/standalone/configuration/standalone.xml file and review the changes.

2. The following key-store was added to the elytron subsystem:

   <key-stores>
       <key-store name="qsKeyStore">
           <credential-reference clear-text="secret"/>
           <implementation type="JKS"/>
           <file path="server.keystore" relative-to="jboss.server.config.dir"/>
       </key-store>
   </key-stores>

3. The following key-manager was added to the elytron subsystem:

   <key-managers>
       <key-manager name="qsKeyManager" key-store="qsKeyStore">
           <credential-reference clear-text="secret"/>
       </key-manager>
   </key-managers>

4. The following ssl-context was added to the elytron subsystem:

   <server-ssl-contexts>
       <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" key-manager="qsKeyManager"/>
   </server-ssl-contexts>

5. The https-listener in the undertow subsystem was changed to reference the qsSSLContext ssl-context:

   <https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/>

../shared-doc/build-and-deploy-the-quickstart.adoc

Access the Application

The application will be running at the following URL: https://localhost:8443/{artifactId}/.

../shared-doc/undeploy-the-quickstart.adoc ../shared-doc/restore-standalone-server-configuration.adoc

This script reverts the changes made to the undertow subsystem and it also removes the ssl-context, key-manager, and key-store from the elytron subsystem. You should see the following result when you run the script.

The batch executed successfully
process-state: reload-required

../shared-doc/restore-standalone-server-configuration-manual.adoc

Remove the keystore created for this quickstart

1. Open a terminal and navigate to the {productName} server configuration directory.

   $ cd {jbossHomeName}/standalone/configuration/

2. Remove the keystore generated for this quickstart.

../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc

• Make sure you configure the server by running the JBoss CLI commands as described above under Configure the Server. Stop the server at the end of that step.

• Make sure you restore the server configuration when you have completed testing this quickstart.

../shared-doc/debug-the-application.adoc