include::../shared-doc/attributes.adoc[]

= helloworld-ssl: {productName} Server Side SSL Configuration Example
:author: Giriraj Sharma, Stefan Guilhen
:level: Beginner
:technologies: SSL, Undertow

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

:standalone-server-type: default
:archiveType: war
:includes-cli-scripts:
:restoreScriptName: restore-configuration.cli

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

// System Requirements
include::../shared-doc/system-requirements.adoc[leveloffset=+1]
// Use of {jbossHomeName}
include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]

[[generate_a_keystore_and_self_signed_certificate]]
== Generate a Keystore and Self-signed Certificate

. Open a terminal and navigate to the {productName} server `configuration` directory:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ cd __{jbossHomeName}__/standalone/configuration/
----

. Create a certificate for your server using the following command:
+
[source,options="nowrap"]
----
$>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.

// Back Up the {productName} Standalone Server Configuration
include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+1]
// Start the {productName} Standalone Server
include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+1]

[[configure_the_server]]
== 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.

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

* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.

. 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.
. 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:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{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:
+
[source,options="nowrap"]
----
The batch executed successfully
process-state: reload-required
----

[[test_the_server_ssl_configuration]]
== 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

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

. The following `key-store` was added to the `elytron` subsystem:
+
[source,xml,options="nowrap"]
----
<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>
----

. The following `key-manager` was added to the `elytron` subsystem:
+
[source,xml,options="nowrap"]
----
<key-managers>
    <key-manager name="qsKeyManager" key-store="qsKeyStore">
        <credential-reference clear-text="secret"/>
    </key-manager>
</key-managers>
----

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

+
[source,xml,options="nowrap"]
----
<server-ssl-contexts>
    <server-ssl-context name="qsSSLContext" protocols="TLSv1.2" key-manager="qsKeyManager"/>
</server-ssl-contexts>
----

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

+
[source,xml,options="nowrap"]
----
<https-listener name="https" socket-binding="https" ssl-context="qsSSLContext" enable-http2="true"/>
----

// Build and Deploy the Quickstart
include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+1]

[[access_the_application]]
== Access the Application

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

// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]
// Restore the {productName} Standalone Server Configuration
include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+1]

// Additional information about this script
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.

[source,options="nowrap"]
----
The batch executed successfully
process-state: reload-required
----

// Restore the {productName} Standalone Server Configuration Manually
include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+2]

== Remove the keystore created for this quickstart

. Open a terminal and navigate to the {productName} server `configuration` directory.
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ cd __{jbossHomeName}__/standalone/configuration/
----

. Remove the keystore generated for this quickstart.

// Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse
include::../shared-doc/run-the-quickstart-in-jboss-developer-studio.adoc[leveloffset=+1]

// Additional JBoss Developer Studio instructions
* Make sure you configure the server by running the JBoss CLI commands as described above under xref:configure_the_server[Configure the Server]. Stop the server at the end of that step.
* Make sure you xref:restore-the-server-configuration[restore the server configuration] when you have completed testing this quickstart.

// Debug the Application
include::../shared-doc/debug-the-application.adoc[leveloffset=+1]
