Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[WFLY-18475] helloworld-mutual-ssl-secured Quickstart Common Enhancements CY2023Q3 #886

Merged
merged 3 commits into from
Mar 26, 2024
Merged

[WFLY-18475] helloworld-mutual-ssl-secured Quickstart Common Enhancements CY2023Q3 #886

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
49ee626
[WFLY-18475] helloworld-mutual-ssl-secured Quickstart Common Enhancem…
Oct 10, 2023
aa89803
Replaced old client cert generation instructions with instructions to…
Dec 20, 2023
8560879
[WFLY-18475] moves README.adoc to README-source.adoc; syncs versions …
emmartins Mar 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/quickstart_helloworld-mutual-ssl-secured_ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
name: WildFly helloworld-mutual-ssl-secured Quickstart CI

on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
paths:
- 'helloworld-mutual-ssl-secured/**'
- '.github/workflows/quickstart_ci.yml'

jobs:
call-quickstart_ci:
uses: ./.github/workflows/quickstart_ci.yml
with:
QUICKSTART_PATH: helloworld-mutual-ssl-secured
SERVER_PROVISIONING_SERVER_HOST: https://localhost:8443/
TEST_PROVISIONED_SERVER: true
TEST_OPENSHIFT: false
133 changes: 32 additions & 101 deletions helloworld-mutual-ssl-secured/README-source.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,88 +32,24 @@ include::../shared-doc/add-application-user.adoc[leveloffset=+1]

IMPORTANT: For the purpose of this quickstart the password can contain any valid value because the `ApplicationRealm` will be used for authorization only, for example, to obtain the security roles.

[[set_up_client_keystore_using_java_keytool]]
== Set Up the Client Keystore Using Java Keytool
// 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]

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

. Create the client certificate, which is used to authenticate against the server when accessing a resource through TLS.
+
[source,options="nowrap"]
----
$>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12

What is your first and last name?
[Unknown]: quickstartUser
What is the name of your organizational unit?
[Unknown]: Sales
What is the name of your organization?
[Unknown]: My Company
What is the name of your City or Locality?
[Unknown]: Sao Paulo
What is the name of your State or Province?
[Unknown]: Sao Paulo
What is the two-letter country code for this unit?
[Unknown]: BR
Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR correct?
[no]: yes
----

+
Notice that it sets the `first and last name` to `quickstartUser` and that this matches the user that was added to the `ApplicationRealm`. When authorizing access to a resource, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the `ApplicationRealm` to obtain the client's roles.

. Export the client certificate and create a truststore by importing this certificate.
+
[source,options="nowrap"]
[source,subs="+quotes,attributes+", options="nowrap"]
----
$>keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass secret -keypass secret -file client.crt
$>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret

Owner: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
Issuer: CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR
Serial number: 7fd95ce4
Valid from: Mon Jul 24 16:14:03 BRT 2017 until: Tue Jul 24 16:14:03 BRT 2018
Certificate fingerprints:
MD5: 87:41:C5:CC:E6:79:91:F0:9D:90:AD:9E:DD:57:81:80
SHA1: 55:35:CA:B0:DC:DD:4F:E6:B8:9F:45:4B:4B:98:93:B5:3B:7C:55:84
SHA256: 0A:FC:93:B6:25:5A:74:42:B8:A1:C6:5F:69:88:72:7F:27:A9:81:B0:17:0C:F1:AF:3D:DE:B7:E5:F1:69:66:4B
Signature algorithm name: SHA256withRSA
Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 95 84 BE C6 32 BB 2B 13 4C 7F 5D D4 C4 C8 22 12 ....2.+.L.]...".
0010: CB 09 39 09 ..9.
]
]

Trust this certificate? [no]: yes
Certificate was added to keystore
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-client-cert.cli
----
+
It is worth noticing that the client certificate was imported under the `quickstartUser` alias. When authenticating a client in a `CLIENT_CERT` configuration, the CN (common name) of the client's certificate is extracted by a principal decoder and this name is then used by the `KeyStoreRealm` to match an alias in the trust store. If a trusted certificate is found under this alas, the client is considered authenticated.

. Export client certificate to pkcs12 format.
+
[source,options="nowrap"]
----
$>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret
----
NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.

. The certificate and keystore are now properly configured.

// 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]
The certificate and keystore are now properly configured.

[[configure_the_server]]
== Configure the Server
Expand Down Expand Up @@ -157,7 +93,7 @@ After stopping the server, open the `__{jbossHomeName}__/standalone/configuratio
<key-store name="qsTrustStore">
<credential-reference clear-text="secret"/>
<implementation type="JKS"/>
<file path="client.truststore" relative-to="jboss.server.config.dir"/>
<file path="server.truststore" relative-to="jboss.server.config.dir"/>
</key-store>
----

Expand Down Expand Up @@ -233,22 +169,22 @@ It maps the `client_cert_domain` from the quickstart application to the `http-au
[[test_the_server_ssl_configuration]]
== Test the Server TLS Configuration

To test the TLS configuration, access: https://localhost:8443
To test the TLS configuration, start {productName} and access: https://localhost:8443

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

[[import_the_client_certificate_into_your_browser]]
== 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.
Before you access the application, you must import the _client.keystore.P12_, which holds the client certificate, into your browser.

[[import_the_client_certificate_into_google_chrome]]
=== Import the Certificate into Google Chrome

. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to `link:`chrome://settings/`.
. Click on *Privacy and security* and then on *Security*.
. Scroll down to the *Advanced* section and on the *Manage certificates* screen, select the *Your Certificates* tab and click on the *Import* button.
. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`.
. Select the *client.keystore.p12* file. You will be prompted to enter the password: `secret`.
. The client certificate is now installed in the Google Chrome browser.

[[import_the_client_certificate_into_mozilla_firefox]]
Expand All @@ -258,14 +194,14 @@ Before you access the application, you must import the _clientCert.p12_, which h
. A new window will open. Click on *Privacy & Security* and scroll down to the *Certificates* section.
. Click the *View Certificates* button.
. A new window will open. Select the *Your Certificates* tab and click the *Import* button.
. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`.
. Select the *client.keystore.p12* file. You will be prompted to enter the password: `secret`.
. The certificate is now installed in the Mozilla Firefox browser.

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

// Additional deployment information
If mutual TLS is configured properly and the WAR application is secured, you will be able to access the application only if the DN of client certificate, for example `clientCert.p12`, is same as the one defined in `app-roles.properties` file. Otherwise, it will result in an HTTP error status code of `403 Access Denied/Forbidden`.
If mutual TLS is configured properly and the WAR application is secured, you will be able to access the application only if the DN of client certificate, for example `client.keystore.p12`, is same as the one defined in `app-roles.properties` file. Otherwise, it will result in an HTTP error status code of `403 Access Denied/Forbidden`.

== Access the Application

Expand All @@ -292,6 +228,9 @@ dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYU
ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8=
----

// Server Distribution Testing
:extraStandardDistTestParams: -Dserver.dir=__{jbossHomeName}__
include::../shared-doc/run-integration-tests-with-server-distribution.adoc[leveloffset=+2]
// Undeploy the Quickstart
include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+1]

Expand All @@ -313,6 +252,13 @@ include::../shared-doc/restore-standalone-server-configuration-manual.adoc[level

== Remove the keystores and certificates created for this quickstart

. Run the CLI script to restore client cert configuration:
+
[source,subs="+quotes,attributes+",options="nowrap"]
----
$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-client-cert.cli
----
+
. Open a terminal and navigate to the {productName} server `configuration` directory:
+
[source,subs="+quotes,attributes+",options="nowrap"]
Expand All @@ -322,7 +268,7 @@ $ cd __{jbossHomeName}__/standalone/configuration/
+
NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script.

. Remove the `clientCert.p12`, `client.crt`, and `client.truststore` files that were generated for this quickstart.
. Remove the `client.keystore.P12`, `clientCert.crt`, and `server.truststore` files that were generated for this quickstart.

[[remove_the_client_certificate_from_your_browser]]
== Remove the Client Certificate from Your Browser
Expand All @@ -346,26 +292,11 @@ After you are done with this quickstart, remember to remove the certificate that
. Select the *quickstartUser* certificate and click the *Delete* button.
. The certificate has now been removed from the Mozilla Firefox browser.

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

// Additional Red Hat CodeReady Studio instructions
* Make sure you configure the keystores and client certificates as described under xref:set_up_client_keystore_using_java_keytool[Set Up the Client Keystore Using Java Keytool].
* Depending on the browser you choose, make sure you either xref:import_the_client_certificate_into_google_chrome[import the certificate into Google Chrome] or xref:import_the_client_certificate_into_mozilla_firefox[import the certificate into Mozilla Firefox].
* 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.
* In {JBDSProductName}, choose *Window* –> *Web Browser*, then select the browser you chose to import the certificate.
* To deploy the application, right-click on the *{artifactId}* project and choose *Run As* –> *Run on Server*.
* Make sure you xref:restore_the_server_configuration[restore the {productName} server configuration] when you have completed testing this quickstart.

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

//*************************************************
// Product Release content only
//*************************************************
ifdef::ProductRelease[]
// Build and run sections for other environments/builds
ifndef::ProductRelease,EAPXPRelease[]
:server_provisioning_server_host: https://localhost:8443
include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
endif::[]

// Quickstart not compatible with OpenShift
include::../shared-doc/openshift-incompatibility.adoc[leveloffset=+1]

endif::[]
19 changes: 19 additions & 0 deletions helloworld-mutual-ssl-secured/configure-client-cert.cli
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Configure the client's keystore. This will be used to generate the client's certificate. The path to the keystore file doesn’t actually have to exist yet
/subsystem=elytron/key-store=clientKS:add(path=client.keystore.P12, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=PKCS12)

# Generate a new key pair for the client. We'll use an RSA key of size 2048 and we'll use CN=quickstartUser
/subsystem=elytron/key-store=clientKS:generate-key-pair(alias=quickstartUser, algorithm=RSA, key-size=2048, validity=365, credential-reference={clear-text=secret}, distinguished-name="cn=quickstartUser")

# Export the client's certificate to a file called clientCert.crt
/subsystem=elytron/key-store=clientKS:export-certificate(alias=quickstartUser, path=clientCert.crt, relative-to=jboss.server.config.dir, pem=true)

# Create the server's truststore
/subsystem=elytron/key-store=serverTS:add(path=server.truststore, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, type=PKCS12)

# Import the client's certificate into the server's truststore
/subsystem=elytron/key-store=serverTS:import-certificate(alias=quickstartUser, path=clientCert.crt, relative-to=jboss.server.config.dir, credential-reference={clear-text=secret}, validate=false)

# Persist the changes we've made to the client's keystore and the server's truststore
/subsystem=elytron/key-store=serverTS:store()
/subsystem=elytron/key-store=clientKS:store()

16 changes: 9 additions & 7 deletions helloworld-mutual-ssl-secured/configure-ssl.cli
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,15 @@
# Start batching commands
batch

# Add the keystore and trust manager configuration in the elytron subsystem
/subsystem=elytron/key-store=qsTrustStore:add(path=client.truststore,relative-to=jboss.server.config.dir,type=JKS,credential-reference={clear-text=secret})
/subsystem=elytron/trust-manager=qsTrustManager:add(key-store=qsTrustStore)
# Add the trust manager configuration in the elytron subsystem
/subsystem=elytron/trust-manager=qsTrustManager:add(key-store=serverTS)

# Update the default server-ssl-context to reference the new trust-manager and require client auth
/subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=trust-manager, value=qsTrustManager)
/subsystem=elytron/server-ssl-context=applicationSSC:write-attribute(name=need-client-auth, value=true)

# Add a keystore realm that relies on the truststore to authenticate requests
/subsystem=elytron/key-store-realm=KeyStoreRealm:add(key-store=qsTrustStore)
/subsystem=elytron/key-store-realm=KeyStoreRealm:add(key-store=serverTS)

# Add an aggregate realm that uses the keystore realm for authentication and the application realm for authorization
/subsystem=elytron/aggregate-realm=QuickstartRealm:add(authentication-realm=KeyStoreRealm,authorization-realm=ApplicationRealm)
Expand All @@ -29,10 +28,13 @@ batch
# Add an application-security-domain in the undertow subsystem to map the client_cert_domain from the quickstart app to the http-authentication-factory
/subsystem=undertow/application-security-domain=client_cert_domain:add(http-authentication-factory=quickstart-http-authentication)

# Generate the server's certificate
/subsystem=elytron/key-store=applicationKS:generate-key-pair(alias=server, algorithm=RSA, key-size=2048, validity=365, credential-reference={clear-text=password}, distinguished-name="cn=localhost")

/subsystem=elytron/key-store=applicationKS:store()

# Run the batch commands
run-batch

# Reload the server configuration
reload


#reload
Loading