KEYCLOAK-14392 Adressing input from Lukas.

getting_started/master-docinfo.xml

@@ -4,13 +4,14 @@
 <title>{gettingstarted_name}</title>
 <release>{project_versionDoc}</release>
 <abstract>
-	    <para>This guide consists of basic information and instructions to get started with {project_name_full} {project_versionDoc}</para>
-    </abstract>
+<para>This guide helps you practice using {project_name} to evaluate it before you use it in a production environment. It includes instructions for installing the {project_name} server in standalone mode, creating accounts and realms for managing users and applications, and securing a {appserver_name} server application. 
+</para>
+</abstract>
 <authorgroup>
     <orgname>Red Hat Customer Content Services</orgname>
 </authorgroup>
 <legalnotice lang="en-US" version="5.0" xmlns="http://docbook.org/ns/docbook">
-  <para> 		Copyright <trademark class="copyright"></trademark> 2019 Red Hat, Inc. 	</para>
+  <para> 		Copyright <trademark class="copyright"></trademark> 2020 Red Hat, Inc. 	</para>
   <para>Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at</para>

getting_started/topics.adoc

@@ -1,4 +1,6 @@
-include::topics/overview.adoc[]
+ifeval::[{project_community}==true]
+include::topics/introduction-keycloak.adoc[]
+endif::[]
 include::topics/first-boot.adoc[]
 ifeval::[{project_community}==true]
 include::topics/first-boot/distribution-files-community.adoc[]
@@ -10,7 +12,7 @@ include::topics/first-boot/boot.adoc[]
 include::topics/first-boot/initial-user.adoc[]
 include::topics/first-boot/admin-console.adoc[]
 include::topics/first-realm.adoc[]
-include::topics/first-realm/before.adoc[]
+include::topics/first-realm/realm-definition.adoc[]
 include::topics/first-realm/realm.adoc[]
 include::topics/first-realm/user.adoc[]
 include::topics/first-realm/account.adoc[]
@@ -19,4 +21,4 @@ include::topics/secure-jboss-app/before.adoc[]
 include::topics/secure-jboss-app/install-client-adapter.adoc[]
 include::topics/secure-jboss-app/create-client.adoc[]
 include::topics/secure-jboss-app/subsystem.adoc[]
-include::topics/secure-jboss-app/download-quickstarts.adoc[]
+include::topics/secure-jboss-app/download-quickstarts.adoc[]

getting_started/topics/first-boot.adoc

@@ -1,6 +1,9 @@
+
 [[_install-boot]]
 
-== Installing and Booting
+== Installing a sample instance of {project_name} 
 
-This section describes how to boot a {project_name} server in standalone mode, set up the initial admin user, and log in to the {project_name} admin console.
+This section describes how to install and start a {project_name} server in standalone mode, set up the initial admin user, and log in to the {project_name} admin console.
 
+.Additional resources
+This installation is intended for practice use of {project_name}. For instructions on installation in a production environment and full details on all product features, see the other guides in the {project_name} documentation.

getting_started/topics/first-boot/admin-console.adoc

@@ -1,12 +1,30 @@
+[id="login-admin"]
+=== Logging into the admin console
 
-=== Log in to the Admin Console
+After you create the initial admin account, you can log in to the admin console.  In this console, you add users and register applications to be secured by {project_name}.
 
-After you create the initial admin account, use the following steps to log in to the admin console:
+.Prerequisites
 
-. Click the *Administration Console* link on the *Welcome* page or go directly to the console URL http://localhost:8080/auth/admin/
+* You have an admin account for the admin console.
 
-. Type the username and password you created on the *Welcome* page to open the *{project_name} Admin Console*.
+.Procedure
+. Click the *Administration Console* link on the *Welcome* page or go directly to http://localhost:8080/auth/admin/ (the console URL). 
 +
-.Admin Console
+[NOTE]
+====
+The Administration Console is generally referred to as the admin console for short in {project_name} documentation.
+====
+
+. Enter the username and password you created on the *Welcome* page to open the  *admin console*.
++
+.Admin console login screen
+image:images/admin-login.png[]
++
+The initial screen for the admin console appears.
++
+.Admin console
 image:{project_images}/admin-console.png[]
 
+.Next steps
+
+Now that you can log into the admin console, you can begin creating realms where administrators can create users and give them access to applications. For more details, see xref:_first-steps[Creating a realm and a user].

getting_started/topics/first-boot/boot.adoc

@@ -1,8 +1,16 @@
+[id="boot-server"]
+=== Starting the {project_name} server
 
-=== Booting the Server
+You start the server on the system where you installed it.
 
-To boot the {project_name} server, go to the `bin` directory of the server distribution and run the `standalone` boot script:
+.Prerequisites
+* You saw no errors during the {project_name} server installation.
 
+.Procedure
+. Go to the `bin` directory of the server distribution.
+. Run the `standalone` boot script.
+
++
 .Linux/Unix
 [source,bash,subs=+attributes]
 ----
@@ -10,9 +18,9 @@ $ cd bin
 $ ./standalone.sh
 ----
 
++
 .Windows
 [source,bash,subs=+attributes]
 ----
 > ...\bin\standalone.bat
 ----
-

getting_started/topics/first-boot/distribution-files-community.adoc

@@ -1,16 +1,17 @@
 
-=== Installing Distribution Files
+[id="standalone-keycloak-install"]
+=== Installing the Server
+You can install the server on Linux or Windows. The server download ZIP file contains the scripts and binaries to run the {project_name} server.
 
-Download the {project_name} Server:
+.Procedure
 
-* *keycloak-{project_version}.[zip|tar.gz]*
+. Download *keycloak-{project_version}.[zip|tar.gz]* from  https://www.keycloak.org/downloads.html[Keycloak downloads].
 
-NOTE: This file can be downloaded from https://www.keycloak.org/downloads.html[Keycloak downloads].
+. Place the file in a directory you choose.
 
-The *keycloak-{project_version}.[zip|tar.gz]* file is the server-only distribution. It contains only the scripts and binaries to run the {project_name} server.
-
-Place the file in a directory you choose and use either the `unzip` or `tar` utility to extract it.
+. Unpack the ZIP file using the appropriate `unzip` utility, such as jar, tar, or unzip.
 
++
 .Linux/Unix
 [source,bash,subs=+attributes]
 ----
@@ -21,8 +22,9 @@ or
 $ tar -xvzf keycloak-{project_version}.tar.gz
 ----
 
++
 .Windows
 [source,bash,subs=+attributes]
 ----
 > unzip keycloak-{project_version}.zip
-----
+----

getting_started/topics/first-boot/distribution-files-product.adoc

@@ -1,24 +1,35 @@
 
-=== Installing the Server
+[id="standalone-install"]
+=== Installing the {project_name} server
 
-Download the {project_name} Server:
+For this sample instance of {project_name}, this procedure involves installation in standalone mode. The server download ZIP file contains the scripts and binaries to run the {project_name} server. You can install the server on Linux or Windows.
 
-* *rh-sso-{project_version}.zip*
 
-NOTE: This file can be downloaded from https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[the Red Hat customer portal].
+.Procedure
 
-The *rh-sso-{project_version}.zip* file is the server-only distribution. It contains only the scripts and binaries to run the {project_name} server.
+. Go to the https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Red Hat customer portal].
 
-Place the file in a directory you choose and use the `unzip` utility to unpack it, like this:
+. Download the {project_name} Server: *rh-sso-{project_version}.zip*
 
+. Place the file in a directory you choose.
+
+. Unpack the ZIP file using the appropriate `unzip` utility, such as jar, tar, or unzip.
+
++
 .Linux/Unix
 [source,bash,subs=+attributes]
 ----
-$ jar xf rh-sso-{project_version}.zip
+$ unzip rhsso-{project_version}.zip
+
+or
+
+$ tar -xvzf rh-sso-{project_version}.tar.gz
 ----
 
++
 .Windows
 [source,bash,subs=+attributes]
 ----
-> unzip rh-sso-{project_version}.zip
+$ unzip rhsso-{project_version}.zip
 ----
+

getting_started/topics/first-boot/initial-user.adoc

@@ -1,14 +1,23 @@
 
-=== Creating the Admin Account
+[id="create-admin"]
+=== Creating the admin account
 
-After the server boots, open http://localhost:8080/auth in your web browser. The welcome page will indicate that the server is running.
+Before you can use {project_name}, you need to create an admin account which you use to log in to the {project_name} admin console.
 
-Enter a username and password to create an initial admin user. 
+.Prerequisites
+* You saw no errors when you started the {project_name} server.
 
-This account will be permitted to log in to the `master` realm's administration console, from which you will create realms and users and register applications to be secured by {project_name}.
+.Procedure
 
-NOTE:  You can only create an initial admin user on the Welcome Page if you connect using `localhost`. This is a security
-       precaution. You can create the initial admin user at the command line with the `add-user-keycloak.sh` script. For more information, see the
-       link:{installguide_link}[{installguide_name}] and the link:{adminguide_link}[{adminguide_name}].
+. Open http://localhost:8080/auth in your web browser.
++
+The welcome page opens, confirming that the server is running.
++
+.Welcome page
+image:{project_images}/welcome.png[]
 
+. Enter a username and password to create an initial admin user.
 
+// Additional resources
+// For more information, see the
+// link:{installguide_link}[{installguide_name}] and the link:{adminguide_link}[{adminguide_name}].

getting_started/topics/first-realm.adoc

@@ -1,4 +1,4 @@
 
-== Creating a Realm and User
-
-In this section you will create a new realm within the {project_name} admin console and add a new user to that realm. You will use that new user to log in to your new realm and visit the built-in user account service that all users have access to.
+[id="_first-steps"]
+== Creating a realm and a user
+The first use of the {project_name} admin console is to create a realm and create a user in that realm. You use that user to log in to your new realm and visit the built-in account console, to which all users have access.

getting_started/topics/first-realm/account.adoc

@@ -1,16 +1,24 @@
 
-=== User Account Service
-
-. After you create the new user, log out of the management console by opening the user drop-down menu and selecting *Sign Out*.
-
-. Go to http://localhost:8080/auth/realms/demo/account and log in to the User Account Service of your `demo` realm with the user you just created.
-
-. Type the username and password you created. You will be required to create a permanent password after you successfully log in, unless you changed the *Temporary* setting to *Off* when you created the password.
-
-The user account service page will open. Every user in a realm has access to this account service by default. From this page, you can update profile information and change or add additional credentials. For more information on this service see the link:{adminguide_link}[{adminguide_name}].
+=== Logging into the account console
+Every user in a realm has access to the account console. You use this console to update your profile information and change your credentials. You can now test logging in with that user in the realm that you created.
 
+.Procedure
+. Log out of the admin console by opening the user menu and selecting *Sign Out*.
 
+. Go to http://localhost:8080/auth/realms/demo/account and log in to your `demo` realm as the user that you just created.
 
+. When you are asked to supply a new password, enter a password that you can remember.
++
+.Update password
+image:{project_images}/update-password.png[]
++
+The account console opens for this user.
++
+.Account console
+image:images/account-console.png[]
 
+. Complete the required fields with any values to test using this page.
 
+.Next steps
 
+You are now ready for the final procedure, which is to secure a sample application that runs on {appserver_name}. See xref:_sample-application[Securing a sample application].

getting_started/topics/first-realm/realm-definition.adoc

@@ -0,0 +1,10 @@
+
+[id="realms-users"]
+=== Realms and users
+When you log in to the admin console, you work in a realm, which is a space where you manage objects. Two types of realms exist:
+
+* `Master realm` - This realm was created for you when you first started {project_name}. It contains the admin account you created at the first login. You use this realm only to create other realms.
+
+* `Other realms` - These realms are created by the admin in the master realm. In these realms, administrators create users and applications. The applications are owned by the users.
+
+image:images/master_realm.png[]

getting_started/topics/first-realm/realm.adoc

@@ -1,16 +1,31 @@
 [[_create-realm]]
+=== Creating a realm
 
-=== Creating a New Realm
+As the admin in the master realm, you create the realms where administrators create users and applications.
 
-To create a new realm, complete the following steps:
+.Prerequisites
 
-. Go to http://localhost:8080/auth/admin/ and log in to the {project_name} Admin Console using the account you created in <<_install-boot, Install and Boot>>.
+* {project_name} is installed.
+* You have the initial admin account for the admin console.
 
-. From the *Master* drop-down menu, click *Add Realm*. When you are logged in to the master realm this drop-down menu lists all existing realms.
+.Procedure
 
-. Type `demo` in the *Name* field and click *Create*.
+. Go to http://localhost:8080/auth/admin/ and log in to the {project_name} admin console using the admin account.
 
-When the realm is created, the main admin console page opens. Notice the current realm is now set to `demo`. Switch between managing the `master` realm and the realm you just created by clicking entries in the *Select realm* drop-down menu.
+. From the *Master* menu, click *Add Realm*. When you are logged in to the master realm, this menu lists all other realms.
 
+. Type `demo` in the *Name* field.
++
+.A new realm
+image:{project_images}/add-demo-realm.png[]
++
+NOTE: The realm name is case-sensitive, so make note of the case that you use.
 
+. Click *Create*.
++
+The main admin console page opens with realm set to `demo`.
++
+.Demo realm
+image:{project_images}/demo-realm.png[]
 
+. Switch between managing the `master` realm and the realm you just created by clicking entries in the *Select realm* drop-down list.

getting_started/topics/first-realm/user.adoc

@@ -1,20 +1,37 @@
-[[_create-new-user]]
+[[_create-user]]
 
-=== Creating a New User
+=== Creating a user
 
-To create a new user in the `demo` realm, along with a temporary password for that new user, complete the following steps:
+In the `demo` realm, you create a new user and a temporary password for that new user.
+
+.Procedure
 
 . From the menu, click *Users* to open the user list page.
 
-. On the right side of the empty user list, click *Add User* to open the add user page.
+. On the right side of the empty user list, click *Add User* to open the Add user page.
 
-. Enter a name in the `Username` field; this is the only required field. Flip the *Email Verified* switch from *Off* to *On* and click *Save* to save the data and open the management page for the new user.
+. Enter a name in the `Username` field.
++
+This is the only required field.
++
+.Add user page
+image:{project_images}/add-user.png[]
+
+. Flip the *Email Verified* switch to *On* and click *Save*.
++
+The management page for the new user opens.
 
 . Click the *Credentials* tab to set a temporary password for the new user.
 
-. Type a new password and confirm it. Click *Set Password* to set the user password.  
-
-NOTE: This password is temporary and the user will be required to change it after the first login. To create a password that is persistent, flip the *Temporary* switch from *On* to *Off* before clicking *Set Password*.
-
+. Type a new password and confirm it.
 
+. Click *Set Password* to set the user password to the new one you specified.  
++
+.Manage Credentials page
+image:{project_images}/user-credentials.png[]
++
+[NOTE]
+====
+This password is temporary and the user will be required to change it at the first login. If you prefer to create a password that is persistent, flip the *Temporary* switch to *Off* and click *Set Password*.
+====
 

getting_started/topics/introduction-keycloak.adoc

@@ -0,0 +1,4 @@
+
+== Trying out Keycloak
+
+This guide helps you practice using {project_name} to evaluate it before you use it in a production environment. It includes instructions for installing the {project_name} server in standalone mode, creating accounts and realms for managing users and applications, and securing a {appserver_name} server application.

getting_started/topics/overview.adoc

@@ -1,7 +1,11 @@
 
-== Overview
+[id="basic-install"]
+== Installing a sample instance of {project_name} 
 
-This guide helps you get started with {project_name}. It covers server configuration and use of the default database. Advanced deployment options are not covered. For a deeper description of features or configuration options, consult the other reference guides.
+This section describes how to install and start a {project_name} server in standalone mode, set up the initial admin user, and log in to the {project_name} Admin Console.
+
+.Additional resources
+This installation is intended for practice use of {project_name}. For instructions on installation in a production environment and full details on all product features, see the other guides in the {project_name} documentation.
 
 ifeval::[{project_product}==true]
 {project_name} is based on the open source link:https://www.keycloak.org/[Keycloak] community project, which has its documentation link:https://www.keycloak.org/documentation.html[here].

getting_started/topics/secure-jboss-app.adoc

@@ -1,9 +1,9 @@
 
-== Securing a JBoss Servlet Application
+[id="_sample-application"]
+== Securing a sample application
 
-This section describes how to secure a Java servlet application on the {appserver_name} application server by:
+Now that you have an admin account, a realm, and a user, you can use {project_name} to secure a sample {appserver_name} servlet application. You install a {appserver_name} client adapter, register the application in the admin console, modify the {appserver_name} instance to work with {project_name}, and use {project_name} with some sample code to secure the application.
 
-* Installing the {project_name} client adapter on a {appserver_name} application server distribution
-* Creating and registering a client application in the {project_name} admin console
-* Configuring the application to be secured by {project_name}
+.Prerequisites
 
+* You need to adjust the port used by {project_name} to avoid port conflicts with {appserver_name}.

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

@@ -1,14 +1,37 @@
 
-=== Before You Start
+=== Adjusting the port used by {project_name}
 
-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>>.
+The instructions in this guide apply to running {appserver_name} on the same machine as the {project_name} server. In this situation, even though {appserver_name} is bundled with {project_name}, you cannot use {appserver_name} as an application container. You must run a separate {appserver_name} instance for your servlet application.
 
-There is one caveat: Even though {appserver_name} is bundled with {project_name}, you cannot use this as an application container.  Instead, 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 avoid port conflicts, you need different ports to run {project_name} and {appserver_name}.
 
-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.
+.Prerequisites
 
-To start the {project_name} server while also adjusting the port:
+* You have an admin account for the admin console.
+* You created a demo realm.
+* You created a user in the demo realm.
 
+.Procedure
+
+ifeval::[{project_community}==true]
+. Download WildFly from link:https://wildfly.org[WildFly.org].
+endif::[]
+ifeval::[{project_product}==true]
+. Download JBoss EAP 7.3 from the https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform&downloadType=distributions[Red Hat customer portal].
+endif::[]
+
+. Unzip the downloaded {appserver_name}.
++
+[source,bash,subs=+attributes]
+----
+$ unzip <filename>.zip
+----
+
+. Change to the {project_name} root directory.
+
+. Start the {project_name} server by supplying a value for the `jboss.socket.binding.port-offset` system property. This value is added to the base value of every port opened by the {project_name} server. In this example, *100* is the value.
+
++
 .Linux/Unix
 [source,bash,subs=+attributes]
 ----
@@ -16,12 +39,13 @@ $ cd bin
 $ ./standalone.sh -Djboss.socket.binding.port-offset=100
 ----
 
++
 .Windows
 [source,bash,subs=+attributes]
 ----
 > ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
 ----
 
-After starting {project_name}, go to http://localhost:8180/auth/admin/ to access the admin console.
-
-
+. Confirm that the {project_name} server is running. Go to http://localhost:8180/auth/admin/ .
++
+If the admin console opens, you are ready to install a client adapter that enables {appserver_name} to work with {project_name}.

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

@@ -1,33 +1,47 @@
 
-=== Creating and Registering the Client
+=== Registering the {appserver_name} application
 
-To define and register the client in the {project_name} admin console, complete the following steps:
+You can now define and register the client in the {project_name} admin console.
 
-. Log in to the admin console with your admin account.  
+.Prerequisites
 
-. 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.
+* You installed a client adapter to work with {appserver_name}.
+
+.Procedure 
+
+. Log in to the admin console with your admin account: http://localhost:8180/auth/admin/
+
+. In the top left drop-down list, select the `Demo` realm.
+
+. Click `Clients` in the left side menu to open the Clients page.
 +
 .Clients
 image:{project_images}/clients.png[]
 
 . On the right side, click *Create*.  
 
-. Complete the fields as shown here:
+. On the Add Client dialog, create a client called *vanilla* by completing the fields as shown below:
 +
 .Add Client
 image:{project_images}/add-client.png[]
 
-. Click *Save* to create the client application entry.
+. Click *Save*.
 
-. Click the *Installation* tab in the {project_name} admin console to obtain a configuration template.
+. On the *Vanilla* client page that appears, click the *Installation* tab.
 
-. Select *Keycloak OIDC JBoss Subsystem XML* to generate an XML template. Copy the contents for use in the next section.
+. Select *Keycloak OIDC JSON* to generate a file that you need in a later procedure.
++
+.Keycloak.json file
+image:{project_images}/client-install-selected.png[]
+
+. Click *Download* to save *Keycloak.json* in a location that you can find later.
+
+
+. Select *Keycloak OIDC JBoss Subsystem XML* to generate an XML template.
 +
 .Template XML
 image:{project_images}/client-install-selected.png[]
 
-
-
-
+. Click *Download* to save a copy for use in the next procedure, which involves {appserver_name} configuration.
 
 

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

@@ -1,37 +1,54 @@
 
-=== Downloading, Building, and Deploying Application Code
+[id="deploy-code"]
+=== Installing sample code to secure the application
 
-You must have the following installed on your machine and available in your PATH before you continue:
+The final procedure is to make this application secure by installing some sample code from the {quickstartRepo_link} repository. The quickstarts work with the most recent {project_name} release.
+
+The sample code is the *app-profile-jee-vanilla* quickstart. It demonstrates how to change a JavaEE application that is secured with basic authentication without changing the WAR. The {project_name} client adapter subsystem changes the authentication method and injects the configuration. 
+
+.Prerequisites
+
+You have the following installed on your machine and available in your PATH.
 
 * Java JDK 8
-* Apache Maven 3.3.3 or higher
+* Apache Maven 3.1.1 or higher
 * Git
 
-ifeval::[{project_community}==true]
-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.
+You have a *keycloak.json* file.
 
-endif::[]
+.Procedure
 
-ifeval::[{project_product}==true]
-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::[]
-
-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
+. Make sure your {appserver_name} application server is started.
+. Download the code and change directories using the following commands.
++
 [source, subs="attributes"]
 ----
 $ git clone {quickstartRepo_link}
-$ cd {quickstartRepo_dir}/app-profile-jee-vanilla
+$ cd {quickstartRepo_dir}/app-profile-jee-vanilla/config
+----
+
+. Copy the `keycloak.json` file to the current directory.
+
+. Move one level up to the `app-profile-jee-vanilla` directory.
+
+. Install the code using the following command.
++
+[source, subs="attributes"]
+----
 $ mvn clean wildfly:deploy
 ----
 
-During installation, you will see some text scroll by in the application server console window.
-
-To confirm that the application is successfully deployed, go to http://localhost:8180/vanilla and a login page should appear.
-
-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. 
+. Confirm that the application installationt succeeded. Go to http://localhost:8080/vanilla where a login page should appear.
++
+.Login page confirming success
+image:images/vanilla.png[]
 
+. Log in using the account that you created in the demo realm.
++
+.Login page to demo realm
+image:images/demo-login.png[]
++
+A message appears indicating you have completed a successful use of {project_name} to protect a sample {appserver_name} application.  Congratulations!
++
+.Complete success
+image:images/success.png[]

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

@@ -1,94 +1,209 @@
 
-=== Installing the Client Adapter
+=== Installing the {appserver_name} client adapter
 
-Download the {appserver_name} distribution and extract it from the compressed file into a directory on your machine.
+When {appserver_name} and {project_name} are installed on the same machine, {appserver_name} requires some modification. To make this modification, you install a {project_name} client adapter.
 
+.Prerequisites
+
+* {appserver_name} is installed.
+
+* You have a backup of the `../standalone/configuration/standalone.xml` file if you have customized this file.
+
+.Procedure
 ifeval::[{project_community}==true]
-Download the WildFly OpenID Connect adapter distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
+. Download the *WildFly OpenID Connect Client Adapter* distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
 endif::[]
 
 ifeval::[{project_product}==true]
-Download the RH-SSO-{project_version}-eap7-adapter.zip distribution.
+. Download the *Client Adapter for EAP 7* from the https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Red Hat customer portal].
 endif::[]
 
-Extract the contents of this file into the root directory of your {appserver_name} distribution.
+. Change to the root directory of {appserver_name}.
 
-Run the appropriate script for your platform:
+. Unzip the downloaded client adapter in this directory.
++
+[source,bash,subs=+attributes]
+----
+$ unzip <filename>.zip
+----
+
+. Change to the bin directory.
++
+[source,bash,subs=+attributes]
+----
+$ cd bin
+----
+
+. Run the appropriate script for your platform.
++
+[NOTE]
+====
+If you receive a `file not found`, make sure that you used `unzip` in the previous step.  This method of extraction installs the files in the right place.
+====
 
 ifeval::[{project_product}==true]
-.EAP 6.3 and Linux/Unix
-[source,bash,subs=+attributes]
-----
-$ cd bin
-$ ./jboss-cli.sh --file=adapter-install-offline.cli
-----
-
-.EAP 6.3 and Windows
-[source,bash,subs=+attributes]
-----
-> cd bin
-> jboss-cli.bat --file=adapter-install-offline.cli
-----
-
-.EAP 7.2.5 and Linux/Unix
-[source,bash,subs=+attributes]
-----
-$ cd bin
-$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
-----
-
-.EAP 7.2.5 and Windows
-[source,bash,subs=+attributes]
-----
-> cd bin
-> jboss-cli.bat --file=adapter-elytron-install-offline.cli
-----
-endif::[]
-
-ifeval::[{project_community}==true]
-.WildFly 10 and Linux/Unix
-[source,bash,subs=+attributes]
-----
-$ cd bin
-$ ./jboss-cli.sh --file=adapter-install-offline.cli
-----
-
-.WildFly 10 and Windows
-[source,bash,subs=+attributes]
-----
-> cd bin
-> jboss-cli.bat --file=adapter-install-offline.cli
-----
-
-.Wildfly 11+ and Linux/Unix
-[source,bash,subs=+attributes]
-----
-$ cd bin
-$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
-----
-
-.Wildfly 11+ and Windows
-[source,bash,subs=+attributes]
-----
-> cd bin
-> jboss-cli.bat --file=adapter-elytron-install-offline.cli
-----
-endif::[]
-
-NOTE: This script will make the necessary edits to the `.../standalone/configuration/standalone.xml` file of your app server distribution and may take some time to complete.
-
-
-Start the application server.
-
++
 .Linux/Unix
 [source,bash,subs=+attributes]
 ----
-$ cd bin
-$ ./standalone.sh
+$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
 ----
 
++
 .Windows
 [source,bash,subs=+attributes]
 ----
-> ...\bin\standalone.bat
+> jboss-cli.bat --file=adapter-elytron-install-offline.cli
+----
+endif::[]
+
+ifeval::[{project_community}==true]
++
+.WildFly 10 on Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./jboss-cli.sh --file=adapter-install-offline.cli
+----
+
++
+.WildFly 10 on Windows
+[source,bash,subs=+attributes]
+----
+> jboss-cli.bat --file=adapter-install-offline.cli
+----
+
++
+.Wildfly 11 on Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
+----
+
++
+.Wildfly 11 on Windows
+[source,bash,subs=+attributes]
+----
+> jboss-cli.bat --file=adapter-elytron-install-offline.cli
+----
+endif::[]
+
++
+[NOTE]
+====
+This script makes the necessary edits to the `.../standalone/configuration/standalone.xml` file. 
+====
+
+. Start the application server.
+
++
+.Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./standalone.sh
+----
+
++
+.Windows
+[source,bash,subs=+attributes]
+----
+> ...\standalone.bat
+----
+
+ifeval::[{project_community}==true]
+. Download the *WildFly OpenID Connect Client Adapter* distribution from link:https://www.keycloak.org/downloads.html[keycloak.org].
+endif::[]
+
+ifeval::[{project_product}==true]
+. Download the *Client Adapter for EAP 7* from the https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?downloadType=distributions&product=core.service.rhsso[Red Hat customer portal].
+endif::[]
+
+. Change to the root directory of {appserver_name}.
+
+. Unzip the downloaded client adapter in this directory.
++
+[source,bash,subs=+attributes]
+----
+$ unzip <filename>.zip
+----
+
+. Change to the bin directory.
++
+[source,bash,subs=+attributes]
+----
+$ cd bin
+----
+
+. Run the appropriate script for your platform.
++
+[NOTE]
+====
+If you receive a `file not found`, make sure you used `unzip` in the previous step.  This method of extraction installs the files in the right place.
+====
+
+ifeval::[{project_product}==true]
++
+.EAP 7.3 on Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
+----
+
++
+.EAP 7.3 on Windows
+[source,bash,subs=+attributes]
+----
+> jboss-cli.bat --file=adapter-elytron-install-offline.cli
+----
+endif::[]
+
+ifeval::[{project_community}==true]
++
+.WildFly 10 on Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./jboss-cli.sh --file=adapter-install-offline.cli
+----
+
++
+.WildFly 10 on Windows
+[source,bash,subs=+attributes]
+----
+> jboss-cli.bat --file=adapter-install-offline.cli
+----
+
++
+.Wildfly 11 on Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
+----
+
++
+.Wildfly 11 on Windows
+[source,bash,subs=+attributes]
+----
+> jboss-cli.bat --file=adapter-elytron-install-offline.cli
+----
+endif::[]
+
++
+[NOTE]
+====
+This script makes the necessary edits to the `.../standalone/configuration/standalone.xml` file. 
+====
+
+. Start the application server.
+
++
+.Linux/Unix
+[source,bash,subs=+attributes]
+----
+$ ./standalone.sh
+----
+
++
+.Windows
+[source,bash,subs=+attributes]
+----
+> ...\standalone.bat
 ----

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

@@ -1,16 +1,26 @@
 
-=== Configuring the Subsystem
+[id="configure-appserver"]
+=== Modifying the {appserver_name} instance
 
-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.
+The {appserver_name} servlet application requires additional configuration before it is secured by {project_name}.
 
-. Open the `standalone/configuration/standalone.xml` file in the {appserver_name} instance that the application is deployed on and search for the following text:
+.Prerequisites
+
+* You created a client named *vanilla* in the *demo* realm.
+
+* You saved a template XML file for this client.
+
+.Procedure
+
+. Go to the `standalone/configuration` directory in your {appserver_name} root directory.
+. Open the `standalone.xml` file and search for the following text:
 +
 [source,xml]
 ----
 <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
 ----
 
-. Modify this text to prepare the file for pasting in contents from the *Keycloak OIDC JBoss Subsystem XML* template we obtained from {project_name} admin console *Installation* tab by changing the XML entry from self-closing to using a pair of opening and closing tags:
+. Change the XML entry from self-closing to using a pair of opening and closing tags as shown here:
 +
 [source,xml]
 ----
@@ -18,7 +28,7 @@ To configure the {appserver_name} instance that the application is deployed on s
 </subsystem>
 ----
 
-. Paste the contents of the template within the `<subsystem>` element, as shown in this example:
+. Paste the contents of the XML template within the `<subsystem>` element, as shown in this example:
 +
 [source,xml]
 ----
@@ -33,7 +43,7 @@ To configure the {appserver_name} instance that the application is deployed on s
 </subsystem>
 ----
 
-. Change the `name` to `vanilla.war`:
+. Change `WAR MODULE NAME.war` to `vanilla.war`:
 +
 [source,xml]
 ----
@@ -45,6 +55,3 @@ To configure the {appserver_name} instance that the application is deployed on s
 
 . Reboot the application server.
 
-. 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>>.
-
-

xref

@@ -1,152 +0,0 @@
-
-[[_installing-operator]]
-=== Installing the {project_operator} on a cluster
-
-To install the {project_operator}, you can use:
-
-* xref:_install_by_olm[The Operator Lifecycle Manager (OLM)]
-* xref:_install_by_command[Command line installation]
-
-[[_install_by_olm]]
-==== Installing using the Operator Lifecycle Manager
-
-ifeval::[{project_community}==true]
-You can install the Operator on an xref:_openshift-olm[OpenShift] or xref:_kubernetes-olm[Kubernetes] cluster.
-
-[[_openshift-olm]]
-===== Installation on an OpenShift cluster
-endif::[]
-
-.Prerequisites
-
-* You have cluster-admin permission or an equivalent level of permissions granted by an administrator.
-
-.Procedure
-
-Perform this procedure on an OpenShift 4.4 cluster.
-
-. Open the OpenShift Container Platform web console.
-
-. In the left column, click `Operators, OperatorHub`.
-
-. Search for {project_name} Operator.
-+
-.OperatorHub tab in OpenShift
-image:{project_images}/operator-openshift-operatorhub.png[]
-
-. Click the {project_name} Operator icon.
-+
-An Install page opens.
-+
-.Operator Install page on OpenShift
-image:{project_images}/operator-olm-installation.png[]
-
-. Click `Install`.
-
-. Select a namespace and click Subscribe.
-+
-.Namespace selection in OpenShift
-image:images/installed-namespace.png[]
-+
-The Operator starts installing.
-
-When the Operator installation completes, you are ready to create custom resources to install {project_name}, create realms, and perform other adminstrative tasks.
-
-ifeval::[{project_community}==true]
-
-[[_kubernetes-olm]]
-===== Installation on a Kubernetes cluster
-
-.Prerequisites
-
-* You have cluster-admin permission or an equivalent level of permissions granted by an administrator.
-
-.Procedure
-
-For a Kubernetes cluster, perform these steps.
-
-. Go to link:https://operatorhub.io/operator/keycloak-operator[Keycloak Operator on OperatorHub.io].
-
-. Click `Install`.
-
-. Follow the instructions on the screen.
-+
-.Operator Install page on Kubernetes
-image:{project_images}/operator-operatorhub-install.png[]
-
-When the Operator installation completes, you are ready to create custom resources to install {project_name}, create realms, and perform other adminstrative tasks.
-endif::[]
-
-.Additional Resources
-
-ifeval::[{project_community}==true]
-* For more information on a Kubernetes installation, see link:https://operatorhub.io/how-to-install-an-operator[How to install an Operator from OperatorHub.io].
-
-* To track what you install and create with the operator, you can now set up a monitoring application. See xref:_monitoring-operator[The Application Monitoring Operator].
-endif::[]
-
-* For more information on OpenShift Operators, see the link:https://docs.openshift.com/container-platform/4.4/operators/olm-what-operators-are.html[OpenShift Operators guide].
-
-* For more information on OpenShift installation, see link:https://access.redhat.com/documentation/en-us/openshift_container_platform/4.4/html/installing/index[Installing and Configuring OpenShift Container Platform clusters].
-
-[[_install_by_command]]
-==== Installing from the command line
-
-You can install the {project_operator} from the command line.
-
-.Prerequisites
-
-You have cluster-admin permission or an equivalent level of permissions granted by an administrator.
-
-.Procedure
-
-. Obtain the software to install from this location: link:{operatorRepo_link}[Github repo].
-
-. Install all required custom resource definitions:
-+
-[source,bash,subs=+attributes]
-----
-$ {create_cmd} -f deploy/crds/
-----
-
-. Create a new namespace (or reuse an existing one) such as the namespace `myproject`:
-+
-[source,bash,subs=+attributes]
-----
-$ {create_cmd} namespace myproject
-----
-
-. Deploy a role, role binding, and service account for the Operator:
-+
-[source,bash,subs=+attributes]
-----
-$ {create_cmd} -f deploy/role.yaml -n myproject
-$ {create_cmd} -f deploy/role_binding.yaml -n myproject
-$ {create_cmd} -f deploy/service_account.yaml -n myproject
-----
-
-. Deploy the Operator:
-+
-[source,bash,subs=+attributes]
-----
-$ {create_cmd} -f deploy/operator.yaml -n myproject
-----
-
-. Confirm that the Operator is running:
-+
-[source,bash,subs=+attributes]
-----
-$ {create_cmd_brief} get deployment keycloak-operator
-NAME                READY   UP-TO-DATE   AVAILABLE   AGE
-keycloak-operator   1/1     1            1           41s
-----
-
-.Additional resources
-
-* To create your first custom resource, see xref:_keycloak_cr[{project_name} installation using a custom resource].
-ifeval::[{project_community}==true]
-* If you want to start tracking all Operator activities before creating custom resources, see the xref:_monitoring-operator[Application Monitoring Operator].
-endif::[]
-
-
-