ifdef::env-github[] :artifactId: helloworld-mutual-ssl-secured endif::[] //*********************************************************************************** // Enable the following flag to build README.html files for JBoss EAP product builds. // Comment it out for WildFly builds. //*********************************************************************************** //:ProductRelease: //*********************************************************************************** // Enable the following flag to build README.html files for EAP XP product builds. // Comment it out for WildFly or JBoss EAP product builds. //*********************************************************************************** //:EAPXPRelease: // This is a universal name for all releases :ProductShortName: JBoss EAP // Product names and links are dependent on whether it is a product release (CD or JBoss) // or the WildFly project. // The "DocInfo*" attributes are used to build the book links to the product documentation ifdef::ProductRelease[] // JBoss EAP release :productName: JBoss EAP :productNameFull: Red Hat JBoss Enterprise Application Platform :productVersion: 8.0 :DocInfoProductNumber: {productVersion} :WildFlyQuickStartRepoTag: 8.0.x :productImageVersion: 8.0.0 :helmChartName: jboss-eap/eap8 endif::[] ifdef::EAPXPRelease[] // JBoss EAP XP release :productName: JBoss EAP XP :productNameFull: Red Hat JBoss Enterprise Application Platform expansion pack :productVersion: 5.0 :DocInfoProductNumber: 8.0 :WildFlyQuickStartRepoTag: XP_5.0.0.GA :productImageVersion: 5.0 :helmChartName: jboss-eap/eap-xp5 endif::[] ifdef::ProductRelease,EAPXPRelease[] :githubRepoUrl: https://github.com/jboss-developer/jboss-eap-quickstarts/ :githubRepoCodeUrl: https://github.com/jboss-developer/jboss-eap-quickstarts.git :jbossHomeName: EAP_HOME :DocInfoProductName: Red Hat JBoss Enterprise Application Platform :DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform :DocInfoPreviousProductName: jboss-enterprise-application-platform :quickstartDownloadName: {productNameFull} {productVersion} Quickstarts :quickstartDownloadUrl: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform&downloadType=distributions :helmRepoName: jboss-eap :helmRepoUrl: https://jbossas.github.io/eap-charts/ // END ifdef::ProductRelease,EAPXPRelease[] endif::[] ifndef::ProductRelease,EAPXPRelease[] // WildFly project :productName: WildFly :productNameFull: WildFly Application Server :ProductShortName: {productName} :jbossHomeName: WILDFLY_HOME :productVersion: 35 :productImageVersion: 35.0 :githubRepoUrl: https://github.com/wildfly/quickstart/ :githubRepoCodeUrl: https://github.com/wildfly/quickstart.git :WildFlyQuickStartRepoTag: 35.0.0.Beta1 :DocInfoProductName: Red Hat JBoss Enterprise Application Platform :DocInfoProductNameURL: red_hat_jboss_enterprise_application_platform :DocInfoProductNumber: 8.0 :DocInfoPreviousProductName: jboss-enterprise-application-platform :helmRepoName: wildfly :helmRepoUrl: http://docs.wildfly.org/wildfly-charts/ :helmChartName: wildfly/wildfly // END ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] endif::[] :source: {githubRepoUrl} // Values for Openshift S2i sections attributes :CDProductName: {productNameFull} for OpenShift :CDProductShortName: {ProductShortName} for OpenShift :CDProductTitle: {CDProductName} :CDProductNameSentence: Openshift release for {ProductShortName} :CDProductAcronym: {CDProductShortName} :CDProductVersion: {productVersion} :EapForOpenshiftBookName: {productNameFull} for OpenShift :EapForOpenshiftOnlineBookName: {EapForOpenshiftBookName} Online :xpaasproduct: {productNameFull} for OpenShift :xpaasproductOpenShiftOnline: {xpaasproduct} Online :xpaasproduct-shortname: {CDProductShortName} :xpaasproductOpenShiftOnline-shortname: {xpaasproduct-shortname} Online :ContainerRegistryName: Red Hat Container Registry :EapForOpenshiftBookName: Getting Started with {ProductShortName} for OpenShift Container Platform :EapForOpenshiftOnlineBookName: Getting Started with {ProductShortName} for OpenShift Online :OpenShiftOnlinePlatformName: Red Hat OpenShift Container Platform :OpenShiftOnlineName: Red Hat OpenShift Online :ImagePrefixVersion: eap80 :ImageandTemplateImportBaseURL: https://raw.githubusercontent.com/jboss-container-images/jboss-eap-openshift-templates :ImageandTemplateImportURL: {ImageandTemplateImportBaseURL}/{ImagePrefixVersion}/ :BuildImageStream: jboss-{ImagePrefixVersion}-openjdk11-openshift :RuntimeImageStream: jboss-{ImagePrefixVersion}-openjdk11-runtime-openshift // OpenShift repository and reference for quickstarts :EAPQuickStartRepo: https://github.com/jboss-developer/jboss-eap-quickstarts :EAPQuickStartRepoRef: 8.0.x :EAPQuickStartRepoTag: EAP_8.0.0.GA // Links to the OpenShift documentation :LinkOpenShiftGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_with_jboss_eap_for_openshift_container_platform/ :LinkOpenShiftOnlineGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_with_jboss_eap_for_openshift_online/ ifdef::EAPXPRelease[] // Attributes for XP releases :EapForOpenshiftBookName: {productNameFull} for OpenShift :EapForOpenshiftOnlineBookName: {productNameFull} for OpenShift Online :xpaasproduct: {productNameFull} for OpenShift :xpaasproductOpenShiftOnline: {productNameFull} for OpenShift Online :xpaasproduct-shortname: {ProductShortName} for OpenShift :xpaasproductOpenShiftOnline-shortname: {ProductShortName} for OpenShift Online :ContainerRegistryName: Red Hat Container Registry :EapForOpenshiftBookName: {productNameFull} for OpenShift :EapForOpenshiftOnlineBookName: {productNameFull} for OpenShift Online :ImagePrefixVersion: eap-xp3 :ImageandTemplateImportURL: {ImageandTemplateImportBaseURL}/{ImagePrefixVersion}/ :BuildImageStream: jboss-{ImagePrefixVersion}-openjdk11-openshift :RuntimeImageStream: jboss-{ImagePrefixVersion}-openjdk11-runtime-openshift // OpenShift repository and reference for quickstarts :EAPQuickStartRepoRef: xp-5.0.x // Links to the OpenShift documentation :LinkOpenShiftGuide: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/{DocInfoProductNumber}/html/using_eclipse_microprofile_in_jboss_eap/using-the-openshift-image-for-jboss-eap-xp_default :LinkOpenShiftOnlineGuide: https://access.redhat.com/documentation/en-us/red_hat_jboss_enterprise_application_platform/{DocInfoProductNumber}/html/using_eclipse_microprofile_in_jboss_eap/using-the-openshift-image-for-jboss-eap-xp_default endif::[] ifndef::ProductRelease,EAPCDRelease,EAPXPRelease[] :ImageandTemplateImportURL: https://raw.githubusercontent.com/wildfly/wildfly-s2i/v{productVersion}.0/ endif::[] //************************* // Other values //************************* :buildRequirements: Java SE 17.0 or later, and Maven 3.6.0 or later :jbdsEapServerName: Red Hat JBoss Enterprise Application Platform 8.0 :javaVersion: Jakarta EE 10 ifdef::EAPXPRelease[] :javaVersion: Eclipse MicroProfile endif::[] :githubRepoBranch: master :guidesBaseUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/ :useEclipseUrl: {guidesBaseUrl}USE_JBDS.adoc#use_red_hat_jboss_developer_studio_or_eclipse_to_run_the_quickstarts :useEclipseDeployJavaClientDocUrl: {guidesBaseUrl}USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_containing_server_and_java_client_projects :useEclipseDeployEARDocUrl: {guidesBaseUrl}USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_ear_project :useProductHomeDocUrl: {guidesBaseUrl}USE_OF_{jbossHomeName}.adoc#use_of_product_home_and_jboss_home_variables :configureMavenDocUrl: {guidesBaseUrl}CONFIGURE_MAVEN_JBOSS_EAP.adoc#configure_maven_to_build_and_deploy_the_quickstarts :addUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#create_users_required_by_the_quickstarts :addApplicationUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#add_an_application_user :addManagementUserDocUrl: {guidesBaseUrl}CREATE_USERS.adoc#add_an_management_user :startServerDocUrl: {guidesBaseUrl}START_JBOSS_EAP.adoc#start_the_jboss_eap_server :configurePostgresDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_database_for_use_with_the_quickstarts :configurePostgresDownloadDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#download_and_install_postgresql :configurePostgresCreateUserDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#create_a_database_user :configurePostgresAddModuleDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#add_the_postgres_module_to_the_jboss_eap_server :configurePostgresDriverDocUrl: {guidesBaseUrl}CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_driver_in_the_jboss_eap_server :configureBytemanDownloadDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#download_and_configure_byteman :configureBytemanDisableDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#disable_the_byteman_script :configureBytemanClearDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#clear_the_transaction_object_store :configureBytemanQuickstartDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts :configureBytemanHaltDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#use_byteman_to_halt_the_application[ :configureBytemanQuickstartsDocUrl: {guidesBaseUrl}CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts :EESubsystemNamespace: urn:jboss:domain:ee:4.0 :IiopOpenJdkSubsystemNamespace: urn:jboss:domain:iiop-openjdk:2.0 :MailSubsystemNamespace: urn:jboss:domain:mail:3.0 :SingletonSubsystemNamespace: urn:jboss:domain:singleton:1.0 :TransactionsSubsystemNamespace: urn:jboss:domain:transactions:4.0 // LinkProductDocHome: https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/ :LinkProductDocHome: https://access.redhat.com/documentation/en/jboss-enterprise-application-platform-continuous-delivery :LinkConfigGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/configuration_guide/ :LinkDevelopmentGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/development_guide/ :LinkGettingStartedGuide: https://access.redhat.com/documentation/en-us/{DocInfoProductNameURL}/{DocInfoProductNumber}/html-single/getting_started_guide/ :LinkOpenShiftWelcome: https://docs.openshift.com/online/welcome/index.html :LinkOpenShiftSignup: https://docs.openshift.com/online/getting_started/choose_a_plan.html :OpenShiftTemplateName: JBoss EAP CD (no https) :ConfigBookName: Configuration Guide :DevelopmentBookName: Development Guide :GettingStartedBookName: Getting Started Guide :JBDSProductName: Red Hat CodeReady Studio :JBDSVersion: 12.15 :LinkJBDSInstall: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/installation_guide/ :JBDSInstallBookName: Installation Guide :LinkJBDSGettingStarted: https://access.redhat.com/documentation/en-us/red_hat_codeready_studio/{JBDSVersion}/html-single/getting_started_with_codeready_studio_tools/ :JBDSGettingStartedBookName: Getting Started with CodeReady Studio Tools // Enable Rendering of Glow configuration in plugin examples :portedToGlow: true = helloworld-mutual-ssl-secured: Securing a Web Application with Mutual (two-way) TLS Configuration and Role-based Access Control :author: Giriraj Sharma, Stefan Guilhen :level: Intermediate :technologies: Mutual TLS, Security, Undertow [abstract] The `helloworld-mutual-ssl-secured` quickstart demonstrates securing a Web application using client certificate authentication with authorization :standalone-server-type: default :archiveType: war :restoreScriptName: restore-configuration.cli :app-user-groups: JBossAdmin == What is it? This example demonstrates the configuration of _mutual TLS authentication_ in {productNameFull} {productVersion} to secure a war application. Mutual TLS provides the same security as TLS, 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 obtain and maintain a digital certificate. We can secure our war application deployed over {productName} with mutual(two-way) client certificate authentication and provide access permissions or privileges to legitimate users. The out of the box configuration for {productName} has one-way TLS enabled by default. This quickstart shows how to configure {productName} with mutual (two-way) TLS authentication in order to secure a WAR application with restricted access. // Link to the quickstart source :leveloffset: +1 ifndef::ProductRelease,EAPXPRelease[] link:https://github.com/wildfly/quickstart/tree/{WildFlyQuickStartRepoTag}/{artifactId}[Browse the source] endif::[] :leveloffset!: // System Requirements :leveloffset: +1 [[system_requirements]] = System Requirements //****************************************************************************** // Include this template to describe the standard system requirements for // running the quickstarts. // // The Forge quickstarts define a `forge-from-scratch` attribute because they // run entirely in CodeReady Studio and have different requirements . //****************************************************************************** The application this project produces is designed to be run on {productNameFull} {productVersion} or later. All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. :leveloffset!: // Use of {jbossHomeName} :leveloffset: +1 ifdef::requires-multiple-servers[] [[use_of_jboss_home_name]] = Use of the {jbossHomeName}_1, {jbossHomeName}_2, and QUICKSTART_HOME Variables This quickstart requires that you clone your `__{jbossHomeName}__` installation directory and run two servers. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables]. In the following instructions, replace `__{jbossHomeName}_1__` with the path to your first {productName} server and replace `__{jbossHomeName}_2__` with the path to your second cloned {productName} server. When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts. endif::[] ifdef::optional-domain-or-multiple-servers[] [[use_of_jboss_home_name]] = Use of the {jbossHomeName}_1, {jbossHomeName}_2, and QUICKSTART_HOME Variables When deploying this quickstart to a managed domain, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables]. When deploying this quickstart to multiple standalone servers, this quickstart requires that you clone your `__{jbossHomeName}__` installation directory and run two servers. In the following instructions, replace `__{jbossHomeName}_1__` with the path to your first {productName} server and replace `__{jbossHomeName}_2__` with the path to your second cloned {productName} server. When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts. endif::[] ifndef::requires-multiple-servers,optional-domain-or-multiple-servers[] [[use_of_jboss_home_name]] = Use of the {jbossHomeName} and QUICKSTART_HOME Variables In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of __{jbossHomeName}__ and __JBOSS_HOME__ Variables]. When you see the replaceable variable __QUICKSTART_HOME__, replace it with the path to the root directory of all of the quickstarts. endif::[] :leveloffset!: // Add the Authorized Application User :leveloffset: +1 [[add_the_application_user]] = Add the Authorized Application User // Note: The group ID syntax must be defined in the calling topic. // using the document attribute :app-user-groups: // Use a comma-delimited list to define more than one group. // // :app-user-groups: guest, users ifdef::app-user-groups[] :app-group-list: {app-user-groups} :app-group-command: -g '{app-user-groups}' endif::app-user-groups[] ifndef::app-user-groups[] :app-group-list: :app-group-command: endif::app-user-groups[] // attr which other sections may check (ifdef) to know if users needs to be added :addQuickstartUser: true This quickstart uses secured application interfaces and requires that you create the following application user to access the running application. [cols="20%,20%,20%,40%",options="headers"] |=== |UserName |Realm |Password |Roles |quickstartUser |ApplicationRealm |quickstartPwd1! |{app-group-list} |=== To add the application user, open a terminal and type the following command: [source,subs="+quotes,attributes+",options="nowrap"] ---- $ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} ---- NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. :leveloffset!: 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. // Back Up the {productName} Standalone Server Configuration :leveloffset: +1 [[back_up_standalone_server_configuration]] = Back Up the {productName} Standalone Server Configuration //****************************************************************************** // Include this template if your quickstart runs in a standalone server and // needs to back up the server configuration file before running // a CLI script to modify the server. //****************************************************************************** // Define the attributes needed for this topic. //****************************************************************************** // This template sets attributes for the different standalone server profiles. // // You must define the `standalone-server-type`. Supported values are: // default // full // full-ha // ha // microprofile // custom //****************************************************************************** // Standalone server with the default profile. ifeval::["{standalone-server-type}"=="default"] :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::[] // Standalone server with the full profile. ifeval::["{standalone-server-type}"=="full"] :serverProfile: full profile :configFileName: standalone/configuration/standalone-full.xml :serverArguments: -c standalone-full.xml endif::[] // Standalone server with the full HA profile. ifeval::["{standalone-server-type}"=="full-ha"] :serverProfile: full HA profile :configFileName: standalone/configuration/standalone-full-ha.xml :serverArguments: -c standalone-full-ha.xml endif::[] // Start the standalone server with the HA profile. ifeval::["{standalone-server-type}"=="ha"] :serverProfile: HA profile :configFileName: standalone/configuration/standalone-ha.xml :serverArguments: -c standalone-ha.xml endif::[] // Start the standalone server with the Eclipse MicroProfile profile. ifeval::["{standalone-server-type}"=="microprofile"] :serverProfile: MicroProfile profile :configFileName: standalone/configuration/standalone-microprofile.xml :serverArguments: -c standalone-microprofile.xml endif::[] // Standalone server with the custom profile. // NOTE: This profile requires that you define the `serverArguments` variable // within the quickstart README.adoc file. For example: // :serverArguments: --server-config=../../docs/examples/configs/standalone-xts.xml ifeval::["{standalone-server-type}"=="custom"] :serverProfile: custom profile endif::[] // If there is no match, use the default profile. ifndef::serverProfile[] :standalone-server-type: default :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::serverProfile[] Before you begin, back up your server configuration file. . If it is running, stop the {productName} server. . Back up the `__{jbossHomeName}__/{configFileName}` file. After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. :leveloffset!: // Start the {productName} Standalone Server :leveloffset: +1 [[start_the_eap_standalone_server]] = Start the {productName} Standalone Server //****************************************************************************** // Include this template if your quickstart requires a normal start of a single // standalone server. // // You must define the `standalone-server-type`. Supported values are: // default // full // full-ha // ha // custom // // * For mobile applications, you can define the `mobileApp` variable in the // `README.adoc` file to add `-b 0.0.0.0` to the command line. This allows // external clients, such as phones, tablets, and desktops, to connect // to the application through through your local network // ::mobileApp: {artifactId}-service // //****************************************************************************** //****************************************************************************** // This template sets attributes for the different standalone server profiles. // // You must define the `standalone-server-type`. Supported values are: // default // full // full-ha // ha // microprofile // custom //****************************************************************************** // Standalone server with the default profile. ifeval::["{standalone-server-type}"=="default"] :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::[] // Standalone server with the full profile. ifeval::["{standalone-server-type}"=="full"] :serverProfile: full profile :configFileName: standalone/configuration/standalone-full.xml :serverArguments: -c standalone-full.xml endif::[] // Standalone server with the full HA profile. ifeval::["{standalone-server-type}"=="full-ha"] :serverProfile: full HA profile :configFileName: standalone/configuration/standalone-full-ha.xml :serverArguments: -c standalone-full-ha.xml endif::[] // Start the standalone server with the HA profile. ifeval::["{standalone-server-type}"=="ha"] :serverProfile: HA profile :configFileName: standalone/configuration/standalone-ha.xml :serverArguments: -c standalone-ha.xml endif::[] // Start the standalone server with the Eclipse MicroProfile profile. ifeval::["{standalone-server-type}"=="microprofile"] :serverProfile: MicroProfile profile :configFileName: standalone/configuration/standalone-microprofile.xml :serverArguments: -c standalone-microprofile.xml endif::[] // Standalone server with the custom profile. // NOTE: This profile requires that you define the `serverArguments` variable // within the quickstart README.adoc file. For example: // :serverArguments: --server-config=../../docs/examples/configs/standalone-xts.xml ifeval::["{standalone-server-type}"=="custom"] :serverProfile: custom profile endif::[] // If there is no match, use the default profile. ifndef::serverProfile[] :standalone-server-type: default :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::serverProfile[] . Open a terminal and navigate to the root of the {productName} directory. . Start the {productName} server with the {serverProfile} by typing the following command. + ifdef::uses-jaeger[] [source,subs="+quotes,attributes+",options="nowrap"] ---- $ __JAEGER_REPORTER_LOG_SPANS=true JAEGER_SAMPLER_TYPE=const JAEGER_SAMPLER_PARAM=1__ __{jbossHomeName}__/bin/standalone.sh {serverArguments} ---- endif::[] ifndef::uses-jaeger[] [source,subs="+quotes,attributes+",options="nowrap"] ---- $ __{jbossHomeName}__/bin/standalone.sh {serverArguments} ---- endif::[] + NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. ifdef::mobileApp[] + Adding `-b 0.0.0.0` to the above command allows external clients, such as phones, tablets, and desktops, to connect through your local network. For example: + [source,subs="+quotes,attributes+",options="nowrap"] ---- $ __{jbossHomeName}__/bin/standalone.sh {serverArguments} -b 0.0.0.0 ---- endif::[] :leveloffset!: [[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,subs="+quotes,attributes+", options="nowrap"] ---- $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-client-cert.cli ---- + NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. The certificate and keystore are now properly configured. [[configure_the_server]] == Configure the Server You configure the SSL context and required security domain 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 ---- . Stop the {productName} server. == Review the Modified Server Configuration After stopping the server, 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"] ---- ---- . The following `trust-manager` was added to the `elytron` subsystem: + [source,xml,options="nowrap"] ---- ---- . The default `ssl-context` was updated to reference the `trust-manager` to enable two-way TLS: + [source,xml,options="nowrap"] ---- ---- + Note that the `https-listener` in the `undertow` subsystem references the `applicationSSC` `server-ssl-context` by default. . The following realms were added to the `elytron` subsystem: + [source,xml,options="nowrap"] ---- ---- + The `aggregate-realm` defines different security realms for authentication and authorization. In this case, the `KeyStoreRealm` is responsible for authenticating the principal extracted from the client's certificate and the `ApplicationRealm` is responsible for obtaining the roles required to access the application. . The following `principal-decoder` and `security-domain` were added to the `elytron` subsystem: + [source,xml,options="nowrap"] ---- ---- + The `x500-attribute-principal-decoder` creates a new `Principal` from the CN attribute of the `X500Principal` obtained from the client's certificate. This new principal is supplied to the security realms and is also the principal returned in methods like `getUserPrincipal` and `getCallerPrincipal`. . The following `http-authentication-factory` was added to the `elytron` subsystem: + [source,xml,options="nowrap"] ---- ---- + It defines the security domain that will handle requests using the `CLIENT_CERT` HTTP mechanism. . The following `application-security-domain` was added to the `undertow` subsystem: + [source,xml,options="nowrap"] ---- ---- + It maps the `client_cert_domain` from the quickstart application to the `http-authentication-factory` shown above, so requests made to the application go through the configured HTTP authentication factory. [[test_the_server_ssl_configuration]] == Test the Server TLS Configuration 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 _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 *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]] === Import the Certificate into Mozilla Firefox . Click the *Edit* menu item on the browser menu and choose *Settings*. . 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 *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 :leveloffset: +1 [[build_and_deploy_the_quickstart]] = Build and Deploy the Quickstart //****************************************************************************** // Include this template if your quickstart does a normal deployment of a archive. // // * Define the `archiveType` variable in the quickstart README file. // Supported values: // :archiveType: ear // :archiveType: war // :archiveType: jar // // * To override the archive name, which defaults to the {artifactId), // define the `archiveName` variable, for example: // :archiveName: {artifactId}-service // // * To override the archive output directory, // define the `archiveDir` variable, for example: // :archiveDir: ear/target // // * To override the Maven command, define the `mavenCommand` variable, // for example: // :mavenCommand: clean install wildfly:deploy //****************************************************************************** // The archive name defaults to the artifactId if not overridden ifndef::archiveName[] :archiveName: {artifactId} endif::archiveName[] // The archive type defaults to war if not overridden ifndef::archiveType[] :archiveType: war endif::archiveType[] // Define the archive file name as the concatenation of "archiveName" + "." + "archiveType+ :archiveFileName: {archiveName}.{archiveType} // If they have not defined the target archive directory, make it the default for the archive type. ifndef::archiveDir[] ifeval::["{archiveType}"=="ear"] :archiveDir: {artifactId}/ear/target endif::[] ifeval::["{archiveType}"=="war"] :archiveDir: {artifactId}/target endif::[] ifeval::["{archiveType}"=="jar"] :archiveDir: {artifactId}/target endif::[] endif::archiveDir[] ifndef::mavenCommand[] ifeval::["{archiveType}"=="ear"] :mavenCommand: clean install endif::[] ifeval::["{archiveType}"=="war"] :mavenCommand: clean package endif::[] ifeval::["{archiveType}"=="jar"] :mavenCommand: clean install endif::[] endif::mavenCommand[] . Make sure {productName} server is started. . Open a terminal and navigate to the root directory of this quickstart. ifdef::reactive-messaging[] . Run this command to enable the MicroProfile Reactive Messaging functionality on the server + [source,subs="attributes+",options="nowrap"] ---- $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-reactive-messaging.cli ---- endif::reactive-messaging[] . Type the following command to build the quickstart. + [source,subs="attributes+",options="nowrap"] ---- $ mvn {mavenCommand} ---- . Type the following command to deploy the quickstart. + [source,subs="attributes+",options="nowrap"] ---- $ mvn wildfly:deploy ---- This deploys the `{archiveDir}/{archiveFileName}` to the running instance of the server. You should see a message in the server log indicating that the archive deployed successfully. :leveloffset!: // 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 `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 The application will be running at the following URL: https://localhost:8443/{artifactId} A page displaying the caller principal and the client certificate used for mutual TLS should be visible: [source,options="nowrap"] ---- Hello World ! Mutual TLS client authentication is successful and your war app is secured.!! Caller Principal: quickstartUser Client Certificate Pem: MIIDhTCCAm2gAwIBAgIEf9lc5DANBgkqhkiG9w0BAQsFADBzMQswCQYDVQQGEwJCUjESMBAGA1UECBMJU2FvIFBhdW xvMRIwEAYDVQQHEwlTYW8gUGF1bG8xEzARBgNVBAoTCk15IENvbXBhbnkxDjAMBgNVBAsTBVNhbGVzMRcwFQYDVQQDEw5xdWlja3N0YXJ0VXNlcjAe Fw0xNzA3MjQxOTE0MDNaFw0xODA3MjQxOTE0MDNaMHMxCzAJBgNVBAYTAkJSMRIwEAYDVQQIEwlTYW8gUGF1bG8xEjAQBgNVBAcTCVNhbyBQYXVsbz ETMBEGA1UEChMKTXkgQ29tcGFueTEOMAwGA1UECxMFU2FsZXMxFzAVBgNVBAMTDnF1aWNrc3RhcnRVc2VyMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A MIIBCgKCAQEAnHwflE8K/ArTPbTeZZEFK+1jtpg9grPSD62GIz/awoIDr6Rf9vCBTpAg4lom62A0BNZDEJKdab/ExNOOBRY+/pOnYlXZTYlDpdQQap 0E7UP5EfHNZsafgpfILCop2LdTuUbcV7tLKBsthJLJ0ZCoG5QJFble+OPxEbissOvIqHfvUJZi34k9ULteLJc330g0uTuDrLgtoFQ0cbHa4FCQ86o8 5EuRPpFeW6EBA3iYE/tKHSYsK7QSajefX6jZjXoZiUflw97SAGL43ZtvNbrKRywEfsVqDpDurjBg2HI+YahuDz5R1QWTSyTHWMZzcyJYqxjXiSf0oK 1cUahn6m5t1wIDAQABoyEwHzAdBgNVHQ4EFgQUlYS+xjK7KxNMf13UxMgiEssJOQkwDQYJKoZIhvcNAQELBQADggEBADkp+R6kSNXJNfihqbDRp3uF tNMG6OgaYsfC7RtNLMdrhvoLlU7uWzxVCFuifvNlWVRiADBHDCRQU2uNRFW35GQSfHQyok4KoBuKlfBtQ+Xu7c8R0JzxN/rPJPXoCbShzDHo1uoz5/ dzXZz0EjjWCPJk+LVEhEvH0GcWAp3x3irpNU4hRZLd0XomY0Z4NnUt7VMBNYDOxVxgT9qcLnEaEpIfYULubLLCFHwAga2YgsKzZYLuwMaEWK4zhPVF ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2Mk14gJGHUnA8= ---- // Server Distribution Testing :extraStandardDistTestParams: -Dserver.dir=__{jbossHomeName}__ :leveloffset: +1 [[run_the_integration_tests_with_server_distribution]] = Run the Integration Tests ifndef::integrationTestsDirectory[:integrationTestsDirectory: src/test/] ifndef::extraStandardDistTestParams[:extraStandardDistTestParams: ] This quickstart includes integration tests, which are located under the `{integrationTestsDirectory}` directory. The integration tests verify that the quickstart runs correctly when deployed on the server. Follow these steps to run the integration tests. . Make sure {productName} server is started. . Make sure the quickstart is deployed. . Type the following command to run the `verify` goal with the `integration-testing` profile activated. + [source,subs="attributes+",options="nowrap"] ---- $ mvn verify -Pintegration-testing {extraStandardDistTestParams} ---- :leveloffset!: // Undeploy the Quickstart :leveloffset: +1 [[undeploy_the_quickstart]] = Undeploy the Quickstart //******************************************************************************* // Include this template if your quickstart does a normal undeployment of an archive. //******************************************************************************* When you are finished testing the quickstart, follow these steps to undeploy the archive. . Make sure {productName} server is started. . Open a terminal and navigate to the root directory of this quickstart. . Type this command to undeploy the archive: + [source,options="nowrap"] ---- $ mvn wildfly:undeploy ---- :leveloffset!: // Restore the {productName} Standalone Server Configuration :leveloffset: +1 [[restore_the_standalone_server_configuration]] = Restore the {productName} Standalone Server Configuration //****************************************************************************** // Include this template if your quickstart does a normal restoration of a single // standalone server configuration. // * It provides a CLI script. // * You can manually restore the backup copy. // // You must define the script file name using the `restoreScriptName` attribute. // For example: // :restoreScriptName: remove-configuration.cli //****************************************************************************** You can restore the original server configuration using either of the following methods. * You can xref:restore_standalone_server_configuration_using_cli[run the `{restoreScriptName}` script] provided in the root directory of this quickstart. * You can xref:restore_standalone_server_configuration_manually[manually restore the configuration] using the backup copy of the configuration file. [[restore_standalone_server_configuration_using_cli]] == Restore the {productName} Standalone Server Configuration by Running the JBoss CLI Script . xref:start_the_eap_standalone_server[Start the {productName} server] as described above. . 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={restoreScriptName} ---- + NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. :leveloffset!: // Additional information about this script This script reverts the changes made to 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 :leveloffset: +2 [[restore_standalone_server_configuration_manually]] = Restore the {productName} Standalone Server Configuration Manually //****************************************************************************** // Include this template if your quickstart does a normal manual restoration // of a single standalone server. //****************************************************************************** //****************************************************************************** // This template sets attributes for the different standalone server profiles. // // You must define the `standalone-server-type`. Supported values are: // default // full // full-ha // ha // microprofile // custom //****************************************************************************** // Standalone server with the default profile. ifeval::["{standalone-server-type}"=="default"] :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::[] // Standalone server with the full profile. ifeval::["{standalone-server-type}"=="full"] :serverProfile: full profile :configFileName: standalone/configuration/standalone-full.xml :serverArguments: -c standalone-full.xml endif::[] // Standalone server with the full HA profile. ifeval::["{standalone-server-type}"=="full-ha"] :serverProfile: full HA profile :configFileName: standalone/configuration/standalone-full-ha.xml :serverArguments: -c standalone-full-ha.xml endif::[] // Start the standalone server with the HA profile. ifeval::["{standalone-server-type}"=="ha"] :serverProfile: HA profile :configFileName: standalone/configuration/standalone-ha.xml :serverArguments: -c standalone-ha.xml endif::[] // Start the standalone server with the Eclipse MicroProfile profile. ifeval::["{standalone-server-type}"=="microprofile"] :serverProfile: MicroProfile profile :configFileName: standalone/configuration/standalone-microprofile.xml :serverArguments: -c standalone-microprofile.xml endif::[] // Standalone server with the custom profile. // NOTE: This profile requires that you define the `serverArguments` variable // within the quickstart README.adoc file. For example: // :serverArguments: --server-config=../../docs/examples/configs/standalone-xts.xml ifeval::["{standalone-server-type}"=="custom"] :serverProfile: custom profile endif::[] // If there is no match, use the default profile. ifndef::serverProfile[] :standalone-server-type: default :serverProfile: default profile :configFileName: standalone/configuration/standalone.xml :serverArguments: endif::serverProfile[] When you have completed testing the quickstart, you can restore the original server configuration by manually restoring the backup copy the configuration file. . If it is running, stop the {productName} server. . Replace the `__{jbossHomeName}__/{configFileName}` file with the backup copy of the file. :leveloffset!: == 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"] ---- $ cd __{jbossHomeName}__/standalone/configuration/ ---- + NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . 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 After you are done with this quickstart, remember to remove the certificate that was imported into your browser. === Remove the Client Certificate from Google Chrome . Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to 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 then click on the arrow to the right of the certificate to be removed. . The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select *Delete*. . Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. === Remove the Client Certificate from Mozilla Firefox . Click the *Edit* menu item on the browser menu and choose *Preferences*. . 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. . Select the *quickstartUser* certificate and click the *Delete* button. . The certificate has now been removed from the Mozilla Firefox browser. // Build and run sections for other environments/builds ifndef::ProductRelease,EAPXPRelease[] :leveloffset: +1 [[build_and_run_the_quickstart_with_provisioned_server]] = Building and running the quickstart application with provisioned {productName} server ifndef::mavenServerProvisioningCommand[] ifeval::["{archiveType}"=="ear"] :mavenServerProvisioningCommand: clean install endif::[] ifeval::["{archiveType}"=="war"] :mavenServerProvisioningCommand: clean package endif::[] ifeval::["{archiveType}"=="jar"] :mavenServerProvisioningCommand: clean install endif::[] endif::mavenServerProvisioningCommand[] ifndef::deploymentTargetDir[] ifndef::deploymentDir[:deploymentTargetDir: target] ifdef::deploymentDir[:deploymentTargetDir: {deploymentDir}/target] endif::deploymentTargetDir[] ifndef::extraStartParams[:extraStartParams: ] ifndef::extraProvisioningTestParams[:extraProvisioningTestParams: ] Instead of using a standard {productName} server distribution, you can alternatively provision a {productName} server to deploy and run the quickstart. The functionality is provided by the WildFly Maven Plugin, and you may find its configuration in the quickstart `pom.xml`: [source,xml,subs="attributes+"] ---- provisioned-server true org.wildfly.plugins wildfly-maven-plugin ${version.server} ... package ... ---- When built, the provisioned {productName} server can be found in the `{deploymentTargetDir}/server` directory, and its usage is similar to a standard server distribution, with the simplification that there is never the need to specify the server configuration to be started. Follow these steps to run the quickstart using the provisioned server. .Procedure . Make sure the server is provisioned. + [source,subs="attributes+",options="nowrap"] ---- $ mvn {mavenServerProvisioningCommand} ---- ifdef::addQuickstartUser[] . Add the quickstart user: + [source,subs="+quotes,attributes+",options="nowrap"] ---- $ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' {app-group-command} ---- endif::[] ifdef::addQuickstartAdmin[] . Add the quickstart admin: + [source,subs="+quotes,attributes+",options="nowrap"] ---- $ {deploymentTargetDir}/server/bin/add-user.sh -a -u 'quickstartAdmin' -p 'adminPwd1!' {admin-group-command} ---- [NOTE] ==== For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. ==== endif::[] . Start the {productName} provisioned server, using the WildFly Maven Plugin `start` goal. + ifndef::deploymentDir[] [source,subs="attributes+",options="nowrap"] ---- $ mvn wildfly:start {extraStartParams} ---- endif::[] ifdef::deploymentDir[] [source,subs="attributes+",options="nowrap"] ---- $ mvn -f {deploymentDir}/pom.xml wildfly:start {extraStartParams} ---- endif::[] . Type the following command to run the integration tests. + [source,subs="attributes+",options="nowrap"] ---- $ mvn verify -Pintegration-testing {extraProvisioningTestParams} ---- . Shut down the {productName} provisioned server. + ifndef::deploymentDir[] [source,subs="attributes+",options="nowrap"] ---- $ mvn wildfly:shutdown ---- endif::[] ifdef::deploymentDir[] [source,subs="attributes+",options="nowrap"] ---- $ mvn -f {deploymentDir}/pom.xml wildfly:shutdown ---- endif::[] :leveloffset!: endif::[] // Quickstart not compatible with OpenShift :leveloffset: +1 [[openshift_incompatibility]] = {xpaasproduct-shortname} Incompatibility This quickstart is not compatible with {xpaasproduct-shortname}. :leveloffset!: