/helloworld-client-ssl/README.md

helloworld-client-ssl: Wildfly mutual SSL(two-way) configuration example
=======================================================================
Author: Giriraj Sharma

Level: Intermediate

Technologies: Mutual SSL, Undertow, Wildfly

Summary: Basic example that demonstrates client mutual SSL authentication in wildlfy.

What is it?
-----------

This example demonstrates the configuration of *client mutual SSL authentication* in *JBoss Enterprise Application Platform 6* or *WildFly*.

Mutual SSL provides the same security as SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. When mutual authentication is used the server would request the client to provide a certificate in addition to the server certificate issued to the client. Mutual authentication requires an extra round trip time for client certificate exchange. In addition the client must buy and maintain a digital certificate.

This quickstart shows how to configure wildfly to enable TLS/SSL configuration for the new wildfly web-subsystem Undertow and enable mutual (two-way) SSL authentication for clients.
Before we run this example, we must create certificates and configure the server to use SSL, https listener and require client verification.

System requirements
-------------------

All you need to build this project is Java 6.0 (Java SDK 1.6) or better, Maven 3.0 or better.

The application this project produces is designed to be run on JBoss Enterprise Application Platform 6 or WildFly.


Configure Maven
---------------

If you have not yet done so, you must [Configure Maven](http://www.jboss.org/jdf/quickstarts/jboss-as-quickstart/#configure_maven) before testing the quickstarts.

## Setup CA, server and client keys using openSSL

Certificate Authority, server and client keys can be generated either viua traditional openSSL tool or via cross-paltform java keytool.

### Setup CA

First of all we need to set up the Certificate Authority (CA) to issue certificate.

    1. First download OpenSSL and install it.
    2. Set up the directory structure and files required by OpenSSL.
    3. Create a directory ~\OpenSSL\workspace and place the openssl.conf file in the workplace.

    ➜ mkdir -p OpenSSL/workspace
    ➜ workspace cd  OpenSSL/workspace
    ➜ workspace mkdir Keys CSR Certificates
    ➜ workspace touch serial.txt database.txt

4. Generate a key for your Root CA. Execute the below OpenSSL command at workspace where you have openssl configuration file.
    
        openssl genrsa -des3 -out  Keys/RootCA.key 2048

5. This will ask for passphrase for the key, please provide the passphrase and remember it. This will be used later.

6. The next step is to create a self-signed certificate for our CA, this certificate will be used to sign and issue other certificates.
        
        openssl req -config openssl.conf -new -x509 -days 360 -key Keys/RootCA.key -out Certificates/RootCA.crt

7. You will be asked to provide the following information:-

        Country Name (2 letter code)  :US
        State or Province Name (full name) :Carolina
        Locality Name (eg, city) :Raleigh
        Organization Name (eg, company) :Sample Inc
        Organizational Unit Name (eg, section) :Web
        Common Name (eg, your websites domain name) :sample.com
        Email Address :sample@sample.com

8. Export root CA certificate into a keystore
  
        keytool -export -alias server -keystore RootCA.keystore -rfc -file Certificates/RootCA.crt -keypass keypassword -storepass keypassword

9. Export root CA certificate into a truststore
        
        keytool -import -file Certificates/RootCA.crt -keystore RootCA.truststore -keypass keypassword -storepass keypassword

Now we can see our CA’s certificate in the Certificates folder and is ready to sign the certificates.
The server/client certificate pair can be used when an application is trying to access a web service which is configured to authenticate the client application using the client ssl certificates. We can follow steps below to create server and client certificate using OpenSSL

### Create the server and client certificate

1. Create private key for the server.
        
        openssl genrsa -des3 -out Keys/server.key 2048

2. Create CSR for the server.

        openssl req -config openssl.cnf -new -key Keys/server.key -out CSR/server.csr

3. Create server certificate.

        openssl ca -config openssl.cnf -days 360 -in CSR/server.csr -out Certificates/server.crt -keyfile Keys/RootCA.key -cert Certificates/RootCA.crt -policy policy_anything

4. Export server certificate into a keystore
  
        keytool -export -alias server -keystore server.keystore -rfc -file Certificates/server.crt -keypass keypassword -storepass keypassword

5. Create private key for the client.

        openssl genrsa -des3 -out Keys/client.key 2048

6. Create CSR for the client.
        
        openssl req -config openssl.cnf -new -key Keys/client.key -out CSR/client.csr

7. Create client certificate.

        openssl ca -config openssl.cnf -days 360 -in CSR/client.csr -out Certificates/client.crt -keyfile Keys/RootCA.key -cert Certificates/RootCA.crt

8. Finally export the client certificate to pkcs format.

        openssl pkcs12 -export -in Certificates/client.crt -inkey Keys/client.key -certfile Certificates/RootCA.crt -out Certificates/clientCert.p12

## Setup CA, server and client keys using Java Keytool

### Create the server and client certificate

1.  Open a command line and navigate to the JBoss server `configuration` directory:

        For Linux:   JBOSS_HOME/standalone/configuration
        For Windows: JBOSS_HOME\standalone\configuration
2. Create a certificate for your server using the following command:

        keytool -genkey -keyalg RSA -keystore server.keystore -storepass keypassword -validity 365

   You'll be prompted for some additional information, such as your name, organizational unit, and location. Enter any values you prefer.
3. Create the client certificate, which is used to authenticate against the server when accessing a resource through SSL.

         keytool -genkey -keystore client.keystore -storepass keypassword -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12
4. Export the client certificate and create a truststore by importing this certificate:

        keytool -exportcert -keystore client.keystore  -storetype pkcs12 -storepass keypassword -keypass keypassword -file client.crt
        keytool -import -file client.crt -keystore client.truststore
5. Export client certificate to pkcs12 format

        keytool -importkeystore -srckeystore client.keystore -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass keypassword

6. The certificates and keystores are now properly configured.

Configure Wildlfy for mutual client SSL authentication
------------------------------------------------------

1.  Open a command line and navigate to the JBoss server `configuration` directory:

        For Linux:   JBOSS_HOME/standalone/configuration
        For Windows: JBOSS_HOME\standalone\configuration
        
2.  Copy `RootCA.trustsore` and `server.keystore` (or `server.keystore` and `client.truststore`) into the JBoss server `configuration` directory.

### Configure The Additional WildFly Security Realm

The next step is to configure the new keystore as a server identity for ssl in the WildFly security-realms section of the standalone.xml (if you're using -ha or other versions, edit those). Make sure to backup the file: `JBOSS_HOME/standalone/configuration/standalone.xml`
 
 In case keys and certificates have been generated using openSSL
 
 `keystore path` can be configured either via `RootCA.keystore` or `server.keystore`.
 
        <management>
            <security-realms>
                <security-realm name="UndertowRealm">
                <server-identities>
                    <ssl>
                        <keystore path="RootCA.keystore" relative-to="jboss.server.config.dir" keystore-password="keypassword" key-password="keypassword"/>
                    </ssl>
                </server-identities>
            </security-realm>
            <authentication>
                    <truststore path="RootCA.truststore" relative-to="jboss.server.config.dir" keystore-password="keypassword"/>
                    <local default-user="$local" skip-group-loading="true"/>
                    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
            </authentication>
            ...
        </management>
        
else In case keys and certificates have been generated using java keytool

        <management>
            <security-realms>
                <security-realm name="UndertowRealm">
                <server-identities>
                    <ssl>
                        <keystore path="server.keystore" relative-to="jboss.server.config.dir" keystore-password="keypassword" key-password="keypassword"/>
                    </ssl>
                </server-identities>
            </security-realm>
            <authentication>
                    <truststore path="client.truststore" relative-to="jboss.server.config.dir" keystore-password="keypassword"/>
                    <local default-user="$local" skip-group-loading="true"/>
                    <properties path="mgmt-users.properties" relative-to="jboss.server.config.dir"/>
            </authentication>
            ...
        </management>

###Configure Undertow Subsystem for SSL

If you're running with the default-server, add the https-listener to the undertow subsystem:

        <subsystem xmlns="urn:jboss:domain:undertow:2.0">
            <server name="default-server">
                <https-listener name="https" socket-binding="https" security-realm="UndertowRealm" verify-client="REQUIRED"/>
                ...
                ...
            </server>
            ...
            ...
        </subsystem>

That's it, now we are ready to connect to the ssl port of our instance `https://localhost:8443/`. Note, that we get the privacy error as the server certificate is self signed. If we need to use a fully signed certificate, we mostly get a PEM file from the Certificate Authority. In such a case, we need to import the PEM into the keystore and truststore.

Test the Server SSL Configuration
---------------------------------

To test the SSL configuration, access: `<https://localhost:8443>`

If it is configured correctly, you should be asked to trust the server certificate.

Import the Certificate into Your Browser
---------------------------------------

Before you access the application, you must import the *clientCert.p12*, which holds the client certificate, into your browser.

#### Import the Certificate into Google Chrome

1. Click the Chrome menu icon (3 horizontal bars) in the upper right on the browser toolbar and choose 'Settings'. This takes you to <chrome://settings/>.
2. At the bottom of the page, click on the 'Show advanced settings...' link.
3. Find the section 'HTTPS/SSL' and click on the 'Manage certificates...' button.
4. In the 'Certificate manager' dialog box, choose the 'Your Certificates' tab and click the 'Import' button.
5. Select the `clientCert.p12` file. You will be prompted to enter the  password: `keypassword`.
6. The certificate is now installed in the Google Chrome browser.

#### Import the Certificate into Mozilla Firefox

1. Click the 'Edit' menu item on the browser menu and choose 'Preferences'.
2. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab.
3. On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button.
4. A new window will open. Select the 'Your Certificates' tab and click the 'Import' button.
5. Select the `clientCert.p12` file. You will be prompted to enter the  password: `keypassword`.
6. The certificate is now installed in the Mozilla Firefox browser.

Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
------------------------------------------------------------------------------

1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:

        For Linux:   JBOSS_HOME/bin/standalone.sh
        For Windows: JBOSS_HOME\bin\standalone.bat

 
Build and Deploy the Quickstart
-------------------------

_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._

1. Make sure you have started the Wildfly Server as described above.
2. Open a command line and navigate to the root directory of one of the quickstart.
3. Type this command to build and deploy the archive:

        For EAP 6:     mvn clean package jboss-as:deploy
        For WildFly:   mvn -Pwildfly clean package wildfly:deploy

4. This will deploy `target/wildfly-helloworld-client-ssl.war` to the running instance of the server.


Access the application 
---------------------

The application will be running at the following URL: `<https://localhost:8443/wildfly-helloworld-client-ssl>`.


Undeploy the Archive
--------------------

1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:

        For EAP 6:     mvn jboss-as:undeploy
        For WildFly:   mvn -Pwildfly wildfly:undeploy

Remove the SSL Configuration
----------------------------

1. If the server is running, stop the JBoss Enterprise Application Platform 6 or WildFly Server.
2. Replace the `WILDFLY_HOME/standalone/configuration/standalone.xml` file with the back-up copy of the file.


Run the Quickstart in JBoss Developer Studio or Eclipse
-------------------------------------
You can also start the server and deploy the quickstarts from Eclipse using JBoss tools.


Debug the Application
------------------------------------

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

        mvn dependency:sources
        mvn dependency:resolve -Dclassifier=javadoc