KEYCLOAK-7127 first set of changes from Getting Started review (#377)

* KEYCLOAK-7127 first set of changes from Getting Started review

* further cleaning up and deleted some graphics that are no longer needed

getting_started/topics/secure-jboss-app.adoc

@@ -1,7 +1,8 @@
 
 == Securing a JBoss Servlet Application
 
-In this section you will learn how to secure a Java Servlet application on the {appserver_name} application server.  You will learn how to install the
+This section describes how to secure a Java servlet application on the {appserver_name} application server by:
-{project_name} Client Adapter onto a {appserver_name} application server distribution.  You will create and register a client application in the
+* Installing the {project_name} client adapter on a {appserver_name} application server distribution
-{project_name} Admin Console.  Finally, you will configure the application to be secured by {project_name}.
+* Creating and registering a client application in the {project_name} admin console
+* Configuring the application to be secured by {project_name}
 

getting_started/topics/secure-jboss-app/before.adoc

@@ -1,15 +1,13 @@
 
 === Before You Start
 
-Before you can participate in this tutorial, you need to complete the installation of {project_name} and create the
+Before you can secure a Java servlet application, you must complete the installation of {project_name} and create the initial admin user as shown in  <<_install-boot, Installing and Booting>>.
-initial admin user as shown in the <<_install-boot, Installing and Booting>> tutorial.  There is one
-caveat to this.  You have to run a separate {appserver_name} instance on the same machine as the
-{project_name} server.  This separate instance will run your Java Servlet application.  Because of this you will
-have to run the {project_name} under a different port so that there are no port conflicts when running on the
-same machine.  Use the `jboss.socket.binding.port-offset` system property on the command line.  The value of this property
-is a number that will be added to the base value of every port opened by the {project_name} server.
 
-To boot the {project_name} server:
+There is one caveat: you must run a separate {appserver_name} instance on the same machine as the {project_name} server to run your Java servlet application. Run the {project_name} using a different port than the {appserver_name}, to avoid port conflicts.
+
+To adjust the port used, change the value of the `jboss.socket.binding.port-offset` system property when starting the server from the command line. The value of this property is a number that will be added to the base value of every port opened by the {project_name} server.
+
+To start the {project_name} server while also adjusting the port:
 
 .Linux/Unix
 [source]
@@ -23,6 +21,6 @@ $ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
 > ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
 ----
 
-After booting up {project_name}, you can then access the admin console at http://localhost:8180/auth/admin/
+After starting {project_name}, go to http://localhost:8180/auth/admin/ to access the admin console.
 
 

getting_started/topics/secure-jboss-app/create-client.adoc

@@ -1,32 +1,27 @@
 
 === Creating and Registering the Client
 
-The next step you have to do is to define and register the client in the {project_name} Admin Console.
+To define and register the client in the {project_name} admin console, complete the following steps:
 
-. Log into
+. Log in to the admin console with your admin account.  
-the Admin Console with your admin account as you did in previous tutorials.  
 
-. In the top left dropdown menu select and manage
+. In the top left drop-down menu select and manage the `Demo` realm. Click `Clients` in the left side menu to open the Clients page.
-the `demo` realm.  Click `Clients` in the left side menu.  The Clients page opens.
 +
 .Clients
 image:{project_images}/clients.png[]
 
-. On the right click *Create*.  
+. On the right side, click *Create*.  
 
-. Complete the fields as shown below:
+. Complete the fields as shown here:
 +
 .Add Client
 image:{project_images}/add-client.png[]
 
-. After clicking the `Save` button your client application entry will be created.  You now have to go back to the {appserver_name}
+. Click *Save* to create the client application entry.
-instance that the application is deployed on and configure it so that this app is secured by {project_name}.  You can obtain
-a template for the configuration you need by going to the `Installation` tab in the client entry in the {project_name} Admin Console.
-+
-.Installation Tab
-image:{project_images}/client-installation.png[]
 
-. Select *Keycloak OIDC JBoss Subsystem XML*.  An XML template is generated that you'll need to cut and paste.
+. Click the *Installation* tab in the {project_name} admin console to obtain a configuration template.
+
+. Select *Keycloak OIDC JBoss Subsystem XML* to generate an XML template. Copy the contents for use in the next section.
 +
 .Template XML
 image:{project_images}/client-install-selected.png[]
@@ -34,3 +29,5 @@ image:{project_images}/client-install-selected.png[]
 
 
 
+
+

getting_started/topics/secure-jboss-app/download-quickstarts.adoc

@@ -1,22 +1,25 @@
 
 === Downloading, Building, and Deploying Application Code
 
-The project and code for the application you are going to secure is available in link:{quickstartRepo_link}[{quickstartRepo_name}].  You will need the following
+You must have the following installed on your machine and available in your PATH before you continue:
-installed on your machine and available in your PATH before you can continue:
 
 * Java JDK 8
 * Apache Maven 3.1.1 or higher
 * Git
 
 ifeval::[{project_community}==true]
-You can obtain the code by cloning the repository at {quickstartRepo_link}. The quickstarts are designed to work with the most recent Keycloak release.
+NOTE: You can obtain the code by cloning the {quickstartRepo_name} repository at {quickstartRepo_link}. The quickstarts are designed to work with the most recent Keycloak release.
+
 endif::[]
 
 ifeval::[{project_product}==true]
-You can obtain the code by cloning the repository at {quickstartRepo_link}. Use the branch matching the version of {project_name} in use.
+NOTE: You can obtain the code by cloning the repository at {quickstartRepo_link}. Use the branch matching the version of {project_name} in use.
+
 endif::[]
 
-Follow these steps to download the code, build it, and deploy it. Make sure your {appserver_name} application server is started before you run these steps.
+Make sure your {appserver_name} application server is started before you continue.
+
+To download, build, and deploy the code, complete the following steps.
 
 .Clone Project
 [source, subs="attributes"]
@@ -26,21 +29,9 @@ $ cd {quickstartRepo_dir}/app-profile-jee-vanilla
 $ mvn clean wildfly:deploy
 ----
 
-You should see some text scroll down in the application server console window.  After the application is successfully deployed go to:
+During installation, you will see some text scroll by in the application server console window.
 
-http://localhost:8080/vanilla
+To confirm that the application is successfully deployed, go to http://localhost:8080/vanilla and a login page should appear.
 
-.Application Login Page
+NOTE: If you click *Login*, the browser will pop up a BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog box will result in a `Forbidden` message being sent back by the server. You can confirm that the application is currently secured via `BASIC` authentication by finding the setting in the application's `web.xml` file. 
-image:{project_images}/app-login-page.png[]
 
-If you open up the application's _web.xml_ file you would see that the application is secured via `BASIC` authentication.
-If you click on the login button on the login page, the browser
-will pop up a BASIC auth login dialog.
-
-
-.Application Login Dialog
-image:{project_images}/client-auth-required.png[]
-
-
-The application is not secured by any identity provider, so anything you enter in the dialog box will result in a `Forbidden` message being
-sent back by the server.  The next section describes how you can take this deployed application and secure it.

getting_started/topics/secure-jboss-app/install-client-adapter.adoc

@@ -1,20 +1,19 @@
 
 === Installing the Client Adapter
 
-Download the {appserver_name} distribution and unzip
+Download the {appserver_name} distribution and extract it from the compressed file into a directory on your machine.
-it into a directory on your machine.
 
 ifeval::[{project_community}==true]
-Next download the WildFly OpenID Connect adapter distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
+Download the WildFly OpenID Connect adapter distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
 endif::[]
 
 ifeval::[{project_product}==true]
-Next download the RH-SSO-{project_version}-eap7-adapter.zip distribution.
+Download the RH-SSO-{project_version}-eap7-adapter.zip distribution.
 endif::[]
 
-Unzip this file into the root directory of your {appserver_name} distribution.
+Extract the contents of this file into the root directory of your {appserver_name} distribution.
 
-Next perform the following actions:
+Run the appropriate script for your platform:
 
 .WildFly 10 and Linux/Unix
 [source]
@@ -46,8 +45,9 @@ $ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
 ----
 endif::[]
 
-This script will make the appropriate edits to the _.../standalone/configuration/standalone.xml_ file of your app
+NOTE: This script will make the necessary edits to the `.../standalone/configuration/standalone.xml` file of your app server distribution. 
-server distribution.  Finally, boot the application server.
+
+Start the application server.
 
 .Linux/Unix
 [source]

getting_started/topics/secure-jboss-app/subsystem.adoc

@@ -1,17 +1,16 @@
 
 === Configuring the Subsystem
 
-Now that you have copied the XML template from the Installation page, you need to paste this into the _standalone.xml_ file
+To configure the {appserver_name} instance that the application is deployed on so that this app is secured by {project_name}, complete the following steps.
-that resides in the _standalone/configuration_ directory of the application server instance on which your application is deployed.
 
-. Open the standalone/configuration/standalone.xml file and search for the following text:
+. Open the `standalone/configuration/standalone.xml` file in the {appserver_name} instance that the application is deployed on and search for the following text:
 +
 [source,xml]
 ----
 <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
 ----
 
-. Modify this to prepare it for pasting in your template from the Installation page:
+. Modify this text to prepare the file for pasting in contents from the *Keycloak OIDC JBoss Subsystem XML* template we obtained {project_name} admin console *Installation* tab by changing the XML entry from self-closing to using a pair of opening and closing tags:
 +
 [source,xml]
 ----
@@ -19,7 +18,7 @@ that resides in the _standalone/configuration_ directory of the application serv
 </subsystem>
 ----
 
-. Within the <subsystem> element, paste in the template. It will look something like this:
+. Paste the contents of the template within the `<subsystem>` element, as shown in this example:
 +
 [source,xml]
 ----
@@ -34,7 +33,7 @@ that resides in the _standalone/configuration_ directory of the application serv
 </subsystem>
 ----
 
-. Change the *WAR MODULE NAME* text to *vanilla* as follows:
+. Change the `name` to `vanilla.war`:
 +
 [source,xml]
 ----
@@ -44,8 +43,8 @@ that resides in the _standalone/configuration_ directory of the application serv
 </subsystem>
 ----
 
-. Reboot your application server.  
+. Reboot the application server.
 
-. Go to http://localhost:8080/vanilla and click *login*. The {project_name} login page opens. You can log in using the user you created in the <<_create-new-user, Creating a New User>> chapter.
+. Go to http://localhost:8080/vanilla and click *Login*. When the {project_name} login page opens, log in using the user you created in <<_create-new-user, Creating a New User>>.