diff --git a/SUMMARY.adoc b/SUMMARY.adoc index de40122809..7003a5b9fa 100755 --- a/SUMMARY.adoc +++ b/SUMMARY.adoc @@ -1,24 +1,24 @@ = {{book.title}} . link:topics/overview.adoc[Overview] - . link:topics/first-boot.adoc[Install and First Time Boot] + . link:topics/first-boot.adoc[Installing and Booting] {% if book.community %} - .. link:topics/first-boot/distribution-files-community.adoc[Installing Server] + .. link:topics/first-boot/distribution-files-community.adoc[Installing the Server] {% endif %} {% if book.product %} - .. link:topics/first-boot/distribution-files-product.adoc[Installing Server] + .. link:topics/first-boot/distribution-files-product.adoc[Installing the Server] {% endif %} - .. link:topics/first-boot/boot.adoc[Boot Server] - .. link:topics/first-boot/initial-user.adoc[Create Admin Account] - .. link:topics/first-boot/admin-console.adoc[Login Into Admin Console] + .. link:topics/first-boot/boot.adoc[Booting the Server] + .. link:topics/first-boot/initial-user.adoc[Creating the Admin Account] + .. link:topics/first-boot/admin-console.adoc[Logging in to the Admin Console] . link:topics/first-realm.adoc[Creating Your First Realm and User] .. link:topics/first-realm/before.adoc[Before You Start] - .. link:topics/first-realm/realm.adoc[Create a New Realm] - .. link:topics/first-realm/user.adoc[Create a New User] + .. link:topics/first-realm/realm.adoc[Creating a New Realm] + .. link:topics/first-realm/user.adoc[Creating a New User] .. link:topics/first-realm/account.adoc[User Account Service] . link:topics/secure-jboss-app.adoc[Securing a JBoss Servlet Application] .. link:topics/secure-jboss-app/before.adoc[Before You Start] - .. link:topics/secure-jboss-app/install-client-adapter.adoc[Install the Client Adapter] - .. link:topics/secure-jboss-app/download-quickstarts.adoc[Download, Build, Deploy Application Code] - .. link:topics/secure-jboss-app/create-client.adoc[Create and Register Client] - .. link:topics/secure-jboss-app/subsystem.adoc[Configure Subsystem] + .. link:topics/secure-jboss-app/install-client-adapter.adoc[Installing the Client Adapter] + .. link:topics/secure-jboss-app/download-quickstarts.adoc[Downloading, Building, and Deploying Application Code] + .. link:topics/secure-jboss-app/create-client.adoc[Creating and Registering the Client] + .. link:topics/secure-jboss-app/subsystem.adoc[Configuring the Subsystem] diff --git a/topics/first-boot.adoc b/topics/first-boot.adoc index 8ab231c943..bbc5500ea0 100755 --- a/topics/first-boot.adoc +++ b/topics/first-boot.adoc @@ -1,6 +1,6 @@ [[_install-boot]] -== Install and Boot +== Installing and Booting This very short tutorial walks you through booting up the server in standalone mode, setting up the initial admin user, and logging into the {{book.project.name}} admin console. diff --git a/topics/first-boot/admin-console.adoc b/topics/first-boot/admin-console.adoc index 8e0042b7df..75101abc93 100755 --- a/topics/first-boot/admin-console.adoc +++ b/topics/first-boot/admin-console.adoc @@ -1,19 +1,21 @@ -=== Login to Admin Console +=== Logging in to the Admin Console -After you create the initial admin account, click on the _Administration Console_ link on the bottom of the Welcome Page. -Alternatively you can go to the console url directly at http://localhost:8080/auth/admin/ +After you create the initial admin account, you can log in to the Admin Console by completing the following steps: +. At the bottom of the Welcome page click the _Administration Console_ link. +Alternatively you can go to the console URL directly at http://localhost:8080/auth/admin/ ++ .Login Page image:../../{{book.images}}/login-page.png[] -Enter the username and password you created on the Welcome Page. This will bring you to the {{book.project.name}} Admin Console. - +. Type the username and password you created on the Welcome page. The {{book.project.name}} Admin Console page opens. ++ .Admin Console image:../../{{book.images}}/admin-console.png[] -NOTE: If you are curious about a certain feature, button, or field within the Admin Console, simply hover your mouse - over any question mark `?` icon. This will pop up tooltip text to describe the area of the console you are interested in. +NOTE: If you are curious about a certain feature, button, or field within the Admin Console, hover your mouse + over the question mark `?` icon. This will pop up tooltip text to describe the area of the console you are interested in. The image above shows the tooltip in action. diff --git a/topics/first-boot/boot.adoc b/topics/first-boot/boot.adoc index 2240abb56c..120e2b8864 100755 --- a/topics/first-boot/boot.adoc +++ b/topics/first-boot/boot.adoc @@ -1,5 +1,5 @@ -=== Boot the Server +=== Booting the Server To boot the {{book.project.name}} server, go to the _bin/_ directory of the server distribution. diff --git a/topics/first-boot/distribution-files-product.adoc b/topics/first-boot/distribution-files-product.adoc index c79ed45aa1..5665ce34cc 100755 --- a/topics/first-boot/distribution-files-product.adoc +++ b/topics/first-boot/distribution-files-product.adoc @@ -1,11 +1,11 @@ -=== Installing Distribution Files +=== Installing the Server The {{book.project.name}} Server is contained in one distribution file: * 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' -The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server only distribution. It contains nothing other than the scripts and binaries +The 'RH-SSO-{{book.project.version}}.[zip|tar.gz]' file is the server-only distribution. It contains only the scripts and binaries to run the {{book.project.name}} server. To unpack these files run the `unzip` or `gunzip` and `tar` utilities. diff --git a/topics/first-boot/initial-user.adoc b/topics/first-boot/initial-user.adoc index eb5f49ad3d..954b300115 100755 --- a/topics/first-boot/initial-user.adoc +++ b/topics/first-boot/initial-user.adoc @@ -1,17 +1,17 @@ -=== Create Admin Account +=== Creating the Admin Account -After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this: +After the server boots, open your browser and go to the http://localhost:8080/auth URL. The page should look like this: .Welcome Page image:../../{{book.images}}/initial-welcome-page.png[] -{{book.project.name}} does not have any configured admin account out of the box. You must create one on the Welcome Page. +{{book.project.name}} does not have a configured admin account by default. You must create one on the Welcome page. This account will allow you to create an admin that can log into the _master_ realm's administration console so that -you can start creating realms, users and registering applications to be secured by {{book.project.name}}. +you can start creating realms and users and registering applications to be secured by {{book.project.name}}. -NOTE: You can only create an initial admin user on the Welcome Page if you connect via `localhost`. This is a security - precaution. You can also create the initial admin user at the command line with the `add-user-keycloak.sh` script. This is discussed more in the +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 also create the initial admin user at the command line with the `add-user-keycloak.sh` script. For more details see link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.installguide.link}}[{{book.installguide.name}}] and link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.adminguide.link}}[{{book.adminguide.name}}]. diff --git a/topics/first-realm.adoc b/topics/first-realm.adoc index 97ccb152d8..3bca272459 100755 --- a/topics/first-realm.adoc +++ b/topics/first-realm.adoc @@ -1,6 +1,6 @@ -== Create a Realm and User +== Creating a Realm and User This short tutorial walks you through creating a new realm within the {{book.project.name}} Admin Console and adding -a new user to that realm. With that new user you will log into your new realm and visit the built-in User Account +a new user to that realm. With that new user you will log into your new realm and visit the built-in User Account service that all users have access to. \ No newline at end of file diff --git a/topics/first-realm/account.adoc b/topics/first-realm/account.adoc index 02c0c36dba..b1d7bba5ca 100755 --- a/topics/first-realm/account.adoc +++ b/topics/first-realm/account.adoc @@ -1,20 +1,20 @@ === User Account Service -After creating the user, log out of the management console by clicking the right dropdown menu and selecting *Sign Off*. -Next, log in to the User Account Service of your `demo` realm with the user you just created by clicking this link: +. After creating the user, log out of the management console by clicking the right dropdown menu and selecting *Sign Off*. + +. Log in to the User Account Service of your `demo` realm with the user you just created by clicking this link: User Account Link:: http://localhost:8080/auth/realms/demo/account -Enter the username and temporary password you created. You must create a permanent password after you -successfully log in. - +. Type the username and password you created previously. You must create a permanent password after you successfully log in if you didn't toggle the Temporary switch to *Off* previously. ++ .Update Password image:../../{{book.images}}/update-password.png[] -Finally, you will be brought to the User Account Service. Every user in a realm has access to this Account Service by default. -It allows you to update profile information and change or add additional credentials. For more information on this service see the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.adminguide.link}}[{{book.adminguide.name}}]. +The User Account Service page opens. Every user in a realm has access to this Account Service by default. +You can update profile information and change or add additional credentials. For more information on this service see the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.adminguide.link}}[{{book.adminguide.name}}]. diff --git a/topics/first-realm/before.adoc b/topics/first-realm/before.adoc index 4499ca9801..dca93426a5 100755 --- a/topics/first-realm/before.adoc +++ b/topics/first-realm/before.adoc @@ -2,5 +2,5 @@ === Before You Start Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the -initial admin user as shown in the <> tutorial. +initial admin user as shown in the <> tutorial. diff --git a/topics/first-realm/realm.adoc b/topics/first-realm/realm.adoc index c1749339c0..a7e7640ce4 100755 --- a/topics/first-realm/realm.adoc +++ b/topics/first-realm/realm.adoc @@ -1,29 +1,27 @@ [[_create-realm]] -=== Create a New Realm +=== Creating a New Realm -Login to the {{book.project.name}} Admin Console using the account you created in the +To create a new realm, complete the following steps: + +. Log in to the {{book.project.name}} Admin Console using the account you created in the <> tutorial. Admin Console Link:: http://localhost:8080/auth/admin/ -Place the mouse over the top left corner drop down menu that is titled with `Master`. If you are logged in the master realm -this drop down menu lists all the realms created. The last entry of this drop down menu is always `Add Realm`. Click -this to add a realm. - +. In the top left corner dropdown menu that is titled `Master`, click *Add Realm*. If you are logged in to the master realm this dropdown menu lists all the realms created. The Add Realm page opens. ++ .Add Realm Menu image:../../{{book.images}}/add-realm-menu.png[] -This menu option will bring you to the `Add Realm` page. You will be creating a brand new realm from scratch so -enter in `demo` for the realm name and click `Create`. - +. You will be creating a brand new realm from scratch so +type `demo` for the realm name and click `Create`. ++ .Create Realm image:../../{{book.images}}/create-realm.png[] -After creating the realm you are brought back to the main Admin Console page. The current realm will now be set to -`demo`. You can switch between managing the `master` realm and the realm you just created by doing a mouseover on the -top left corner drop down menu. +After creating the realm the main Admin Console page opens. The current realm is now set to `demo`. You can switch between managing the `master` realm and the realm you just created by clicking the top left corner dropdown menu. diff --git a/topics/first-realm/user.adoc b/topics/first-realm/user.adoc index 0e225e5d4f..8119617729 100755 --- a/topics/first-realm/user.adoc +++ b/topics/first-realm/user.adoc @@ -1,31 +1,32 @@ [[_create-new-user]] -=== Create a New User +=== Creating a New User -In this section you are going to create a new user in the `demo` realm as well as a temporary password for that account. -The first step is to click on the `Users` in the left menu bar. +To create a new user in the `demo` realm as well as a temporary password for that account, complete the following steps: +. In the left menu bar click *Users*. The user list page opens. ++ .Users image:../../{{book.images}}/users.png[] -This menu option brings you to the user list page. On the right side of the empty user list, you should see an `Add User` -button. Click that to start creating your new user. +. On the right side of the empty user list, click *Add User*. ++ .Add User image:../../{{book.images}}/add-user.png[] -The only required field is `Username`. Click save. This will bring you to the management page for your new user. - -The next step is to define a temporary password for your new user. Click on the `Credentials` tab to bring you to -the page that will allow you to do this. +. The only required field is `Username`. When you are finished, click *Save*. The management page for your new user opens. +. The next step is to define a temporary password for your new user. Click the *Credentials* tab. ++ .Set Temporary Password image:../../{{book.images}}/credentials.png[] -Enter a new password and retype it within the `Password Confirmation` field. Once you do this a red `Reset Password` -button should reappear. Clicking on that will reset the user's password to the new one you specified. Please note that -this is a temporary password and the user will be required to change it after they first log in. You can make it permanent -by flipping the `Temporary` switch from `On` to `Off` before you click the `Reset Password` button. +. Type a new password and confirm it. A red *Reset Password* button is displayed. +. Click *Reset Password* to reset the user password to the new one you specified. + +NOTE: This password is temporary and the user will be required to change it after first login. You can make it permanent +by flipping the *Temporary* switch from *On* to *Off* before clicking *Reset Password*. diff --git a/topics/overview.adoc b/topics/overview.adoc index 6086dd7070..1b5038ce2a 100755 --- a/topics/overview.adoc +++ b/topics/overview.adoc @@ -2,6 +2,6 @@ == Overview The purpose of this guide is to get you up and running as quickly as possible so that you can -play with and test drive various features that {{book.project.name}} has. It relies heavily on the default database -and server configuration that come out of the box and does not get into any complex deployment options. If you want a more -in depth discussion of any features or configuration options, you should consult the various other reference guides available. \ No newline at end of file +play with and test-drive various features that {{book.project.name}} has. It relies heavily on the default database +and server configuration and does not cover any complex deployment options. If you want a more +in-depth discussion of any features or configuration options, consult the various reference guides available. \ No newline at end of file diff --git a/topics/secure-jboss-app/before.adoc b/topics/secure-jboss-app/before.adoc index 8d6c6867fc..7951fb9cc9 100755 --- a/topics/secure-jboss-app/before.adoc +++ b/topics/secure-jboss-app/before.adoc @@ -2,7 +2,7 @@ === Before You Start Before you can participate in this tutorial, you need to complete the installation of {{book.project.name}} and create the -initial admin user as shown in the <> tutorial. There is one +initial admin user as shown in the <> tutorial. There is one caveat to this. You have to run a separate {{book.appServer}} instance on the same machine as the {{book.project.name}} server. This separate instance will run your Java Servlet application. Because of this you will have to run the {{book.project.name}} under a different port so that there are no port conflicts when running on the diff --git a/topics/secure-jboss-app/create-client.adoc b/topics/secure-jboss-app/create-client.adoc index 66aa191d4e..38902ff641 100644 --- a/topics/secure-jboss-app/create-client.adoc +++ b/topics/secure-jboss-app/create-client.adoc @@ -1,27 +1,33 @@ -=== Create and Register Client +=== Creating and Registering the Client -The next step you have to do is to define and register the client in the {{book.project.name}} Admin Console. Log into -the Admin Console with your admin account as you did in previous tutorials. In the top left hand drop down menu select and manage -the `demo` realm. Click `Clients` in the left side menu. This will bring you to the `Clients` page. +The next step you have to do is to define and register the client in the {{book.project.name}} Admin Console. +. Log into +the Admin Console with your admin account as you did in previous tutorials. + +. In the top left dropdown menu select and manage +the `demo` realm. Click `Clients` in the left side menu. The Clients page opens. ++ .Clients image:../../{{book.images}}/clients.png[] -On the right hand side you should see a button named `Create`. Click this button and fill in the fields as shown below: +. On the right click *Create*. +. Complete the fields as shown below: ++ .Add Client image:../../{{book.images}}/add-client.png[] -After clicking the `Save` button your client application entry will be created. You now have to go back to the {{book.appServer}} +. After clicking the `Save` button your client application entry will be created. You now have to go back to the {{book.appServer}} instance that the application is deployed on and configure it so that this app is secured by {{book.project.name}}. You can obtain a template for the configuration you need by going to the `Installation` tab in the client entry in the {{book.project.name}} Admin Console. - ++ .Installation Tab image:../../{{book.images}}/client-installation.png[] -Select the `Keycloak OIDC JBoss Subsystem XML` option. This will generate an XML template that you'll need to cut and paste. - +. Select *Keycloak OIDC JBoss Subsystem XML*. An XML template is generated that you'll need to cut and paste. ++ .Template XML image:../../{{book.images}}/client-install-selected.png[] diff --git a/topics/secure-jboss-app/download-quickstarts.adoc b/topics/secure-jboss-app/download-quickstarts.adoc index 03f9274e63..316d29ed0d 100644 --- a/topics/secure-jboss-app/download-quickstarts.adoc +++ b/topics/secure-jboss-app/download-quickstarts.adoc @@ -1,5 +1,5 @@ -=== Download, Build, Deploy Application Code +=== Downloading, Building, and Deploying Application Code The project and code for the application you are going to secure is available in link:{{book.quickstartRepo}}[Red Hat Developers GitHub]. You will need the following installed on your machine and available in your PATH before you can continue: diff --git a/topics/secure-jboss-app/install-client-adapter.adoc b/topics/secure-jboss-app/install-client-adapter.adoc index b8fcc13970..23e92a577e 100644 --- a/topics/secure-jboss-app/install-client-adapter.adoc +++ b/topics/secure-jboss-app/install-client-adapter.adoc @@ -1,5 +1,5 @@ -=== Install the Client Adapter +=== Installing the Client Adapter Download the {{book.appServer}} distribution and unzip it into a directory on your machine. @@ -31,7 +31,7 @@ $ ./jboss-cli.sh --file=adapter-install-offline.cli ---- This script will make the appropriate edits to the _.../standalone/configuration/standalone.xml_ file of your app -server distribution. Finally, just boot the application server. +server distribution. Finally, boot the application server. .Linux/Unix [source] diff --git a/topics/secure-jboss-app/subsystem.adoc b/topics/secure-jboss-app/subsystem.adoc index ce8ea80a11..367915e345 100644 --- a/topics/secure-jboss-app/subsystem.adoc +++ b/topics/secure-jboss-app/subsystem.adoc @@ -1,25 +1,26 @@ -=== Configure Subsystem +=== Configuring the Subsystem -Now that you have copied the XML template from the `Installation` tab, you need to paste this into the _standalone.xml_ file -that lives in the _standalone/configuration_ directory of the application server instance your application is deployed on. -Open this file and search for the following text: +Now that you have copied the XML template from the Installation page, you need to paste this into the _standalone.xml_ file +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: ++ [source,xml] ---- ---- -Modify this a little bit to prepare it for pasting in your template from the `Installation` tab. - +. Modify this to prepare it for pasting in your template from the Installation page: ++ [source,xml] ---- ---- -Within the `subsystem` element, paste in the template. It will look something like this: - +. Within the element, paste in the template. It will look something like this: ++ [source,xml] ---- @@ -33,8 +34,8 @@ Within the `subsystem` element, paste in the template. It will look something l ---- -Change the `WAR MODULE NAME` text to be `vanilla` as follows: - +. Change the *WAR MODULE NAME* text to *vanilla* as follows: ++ [source,xml] ---- @@ -43,7 +44,8 @@ Change the `WAR MODULE NAME` text to be `vanilla` as follows: ---- -Reboot your application's server and now when you visit http://localhost:8080/vanilla and hit the login button, you should -get the {{book.project.name}} login page. You can log in using the user you created in the <> chapter. +. Reboot your application server. + +. Go to http://localhost:8080/vanilla and click *login*. The {{book.project.name}} login page opens. You can log in using the user you created in the <> chapter.