Latest commit 9f51244 Aug 31, 2018

README.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.

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.

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:

  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"/>

Access the Application

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

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

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.