client app

SUMMARY.adoc

@@ -16,5 +16,9 @@
  .. link:topics/first-realm/realm.adoc[Create a New Realm]
  .. link:topics/first-realm/user.adoc[Create a New User]
  .. link:topics/first-realm/account.adoc[User Account Service]
- . link:topics/first-jboss-servlet.adoc[Securing a JBoss Servlet Application]
+ . link:topics/secure-jboss-app.adoc[Securing a JBoss Servlet Application]
- .. link:topics/installation/system-requirements.adoc[System Requirements]
+ .. 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]

book.json

@@ -73,6 +73,11 @@
       "name": "Keycloak Adminstration Guide",
       "link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
     },
+    "appguide": {
+      "name": "Securing Applications with Keycloak",
+      "link": "https://keycloak.gitbooks.io/server-adminstration-guide/content/"
+    },
+    "clientadapter": "RH-SSO-7.0.0.ER10-eap7-adapter.zip",
     "project": {
       "name": "Keycloak",
       "version": "1.9.3.Final-SNAPSHOT"

topics/first-boot/admin-console.adoc

@@ -2,6 +2,7 @@
 === Login to 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/
 
 .Login Page
 image:../../{{book.images}}/login-page.png[]

topics/secure-jboss-app.adoc

@@ -0,0 +1,8 @@
+
+== Securing a JBoss Servlet Application
+
+In this section you will learn how to secure a Java Servlet application on the JBoss EAP 7 or Wildfly 10 application
+servers.  You will learn how to install the {{book.project.name}} Client Adapter onto a JBoss EAP or Wildfly Application Server
+distribution.  You will create and register a client application in the {{book.project.name}} Admin Console.  Finally,
+you will configure the application to be secured by {{book.project.name}}.
+

topics/secure-jboss-app/before.adoc

@@ -0,0 +1,28 @@
+
+=== 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 <<fake/../../first-boot.adoc#_install-boot, Install and Boot>> tutorial.  There is one
+caveat to this.  You are going to have to run a separate JBoss EAP 7 or Wildfly 10 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
+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 {{book.project.name} server.
+
+To boot the {{book.project.name}} server:
+
+.Linux/Unix
+[source]
+----
+$ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
+----
+
+.Windows
+[source]
+----
+> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
+----
+
+After booting up {{book.project.name}}, you can then access the admin console at http://localhost:8180/auth/admin/
+
+

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

@@ -0,0 +1,30 @@
+
+=== Create and Register 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.  Next click the `Clients` left menu.  This will bring you to the `Clients` page.
+
+.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:
+
+.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 JBoss EAP or Wildfly
+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.
+
+.Template XML
+image:../../{{book.images}}/client-install-selected.png[]
+
+
+
+

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

@@ -0,0 +1,41 @@
+
+=== Download, Build, Deploy Application Code
+
+The project and code for the application you are going to secure it at Github.com.  You will need the following
+installed on your machine and available in your PATH before you can continue:
+
+* Java JDK 8
+* Apache Maven 3.1.1 or higher
+
+You can obtain the code by cloning the
+quickstart repo at git@github.com:jboss-developer/rh-sso-quickstarts.git.  Follow these steps to download the code, build it,
+and deploy it.  Make sure your JBoss EAP or Wildfly app server instance is running before you start these steps!
+
+.clone project
+[source]
+----
+$ git clone git@github.com:jboss-developer/rh-sso-quickstarts.git
+$ cd rh-sso-quickstarts/app-profile-jee-vanilla
+$ mvn clean wildfly:deploy
+----
+
+You should see some text scroll down in the app server console window.  After the app is successfully deployed go to:
+
+http://localhost:8080/vanilla
+
+.app login page
+image:../../{{book.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.
+
+
+.app login dialog
+image:../../{{book.images}}/client-auth-required.png[]
+
+
+The app is not secured by any identity provider, so anything you enter in the dialog will result in a `Forbidden` message being
+sent back by the server.  The next section describes how you can take this existing deployed app and secure it.
+
+

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

@@ -0,0 +1,35 @@
+
+=== Install the Client Adapter
+
+Download the JBoss EAP 7 or Wildfly 10 distribution you are going to use to run your example application and unzip
+it into a directory of your choosing on your machine.  Next download the {{book.clientadapter}} distribution.  Unzip
+this file into the root directory of your JBoss EAP or Wildfly 10 distribution.  Next perform the following actions
+
+.Linux/Unix
+[source]
+----
+$ cd bin
+$ ./jboss-cli.sh --file=adapter-install-offline.cli
+----
+
+.Windows
+[source]
+----
+> cd bin
+> jboss-cli.bat --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.
+
+.Linux/Unix
+[source]
+----
+$ .../bin/standalone.sh
+----
+
+.Windows
+[source]
+----
+> ...\bin\standalone.bat
+----

topics/secure-jboss-app/subsystem.adoc

@@ -0,0 +1,50 @@
+
+=== Configure 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:
+
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
+----
+
+Modify this a little bit to prepare it for pasting in your template from the `Installation` tab.
+
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
+</subsystem>
+----
+
+Within the `subsystem` element, paste in the template.  It will look something like this:
+
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
+  <secure-deployment name="WAR MODULE NAME.war">
+    <realm>demo</realm>
+    <realm-public-key>MIIBIjANBgkqhkiG9B</realm-public-key>
+    <auth-server-url>http://localhost:8180/auth</auth-server-url>
+    <public-client>true</public-client>
+    <ssl-required>EXTERNAL</ssl-required>
+    <resource>vanilla</resource>
+  </secure-deployment>
+</subsystem>
+----
+
+Change the `WAR MODULE NAME` text to be `vanilla` as follows:
+
+[source,xml]
+----
+<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
+  <secure-deployment name="vanilla.war">
+  ...
+</subsystem>
+----
+
+Reboot your application's server and now when visit http://localhost:8080/vanilla and hit the login button, you should
+get the {{book.project.name}} login page.
+
+