Merge pull request #56 from pedroigor/RHSSO-620

[RHSSO-620] - Changes to include quickstarts and examples in rhsso-quickstarts

SUMMARY.adoc

@@ -6,7 +6,6 @@
 
    .. link:topics/overview/terminology.adoc[Terminology]
 
-{% if book.community %}
  . link:topics/getting-started/overview.adoc[Getting Started]
 
    .. link:topics/getting-started/hello-world/overview.adoc[Securing a Servlet Application]
@@ -16,7 +15,7 @@
       ... link:topics/getting-started/hello-world/create-resource-server.adoc[Enabling Authorization Services]
 
       ... link:topics/getting-started/hello-world/deploy.adoc[Build, Deploy, and Test Your Application]
-
+{% if book.community %}
    .. link:topics/example/overview.adoc[Examples]
 {% endif %}
 

book-product.json

@@ -13,6 +13,8 @@
     "community": false,
     "product": true,
     "images": "rhsso-images",
+    "appServer": "JBoss EAP 7",
+    "quickstartRepo": "https://github.com/redhat-developer/redhat-sso-quickstarts",
     "project": {
       "name": "Red Hat Single Sign-On",
       "version": "7.1.0",
@@ -28,6 +30,14 @@
       "keycloakgettingstarted": {
         "name": "Getting Started",
         "link": "/paged/getting-started-guide/"
+      },
+      "keycloakinstallingandboot": {
+        "name": "Installing and Boot",
+        "link": "/single/getting-started-guide/#install-boot"
+      },
+      "keycloakinstallclientadapter": {
+        "name": "Installing the Client Adapter",
+        "link": "/single/getting-started-guide/#installing_the_client_adapter"
       }
     }
   }

book.json

@@ -13,6 +13,8 @@
     "community": true,
     "product": false,
     "images": "keycloak-images",
+    "appServer": "WildFly 10",
+    "quickstartRepo": "https://github.com/redhat-developer/redhat-sso-quickstarts",
     "project": {
       "name": "Keycloak",
       "version": "SNAPSHOT",
@@ -28,6 +30,14 @@
       "keycloakgettingstarted": {
         "name": "Getting Started",
         "link": "/getting-started-tutorials/content/"
+      },
+      "keycloakinstallingandboot": {
+        "name": "Installing and Boot",
+        "link": "/getting-started-tutorials/content/topics/first-boot.html"
+      },
+      "keycloakinstallclientadapter": {
+        "name": "Installing the Client Adapter",
+        "link": "/getting-started-tutorials/content/topics/secure-jboss-app/install-client-adapter.html"
       }
     }
   }

topics/getting-started/hello-world/deploy.adoc

@@ -1,7 +1,28 @@
 [[_getting_started_hello_world_deploy]]
 === Build, Deploy, and Test Your Application
 
-Now that the *hello-world-authz-service* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server.
+Now that the *app-authz-vanilla* resource server (or client) is properly configured and authorization services are enabled, it can be deployed to the server.
+
+The project and code for the application you are going to deploy 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:
+
+* Java JDK 8
+* Apache Maven 3.1.1 or higher
+* Git
+
+You can obtain the code by cloning the repository at {{book.quickstartRepo}}. Use the branch matching the version of Red Hat Single Sign-On in use. Follow these steps to download the code.
+
+.Clone Project
+[source, subs="attributes"]
+----
+$ git clone {{book.quickstartRepo}}
+----
+
+The application we are about to build and deploy is located at
+
+----
+$ cd redhat-sso-quickstarts/app-authz-jee-vanilla
+----
 
 ==== Obtaining the Adapter Configuration
 
@@ -9,7 +30,7 @@ You must first obtain the adapter configuration before building and deploying th
 
 To obtain the adapter configuration from the {{book.project.name}} Administration Console, complete the following steps. 
 
-. Click *Clients*. In the client listing, click the *hello-world-authz-service* client application. The Client Details page opens.
+. Click *Clients*. In the client listing, click the *app-authz-vanilla* client application. The Client Details page opens.
 +
 .Client Details
 image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt="Client Details"]
@@ -19,29 +40,30 @@ image:../../../{{book.images}}/getting-started/hello-world/enable-authz.png[alt=
 .Adapter Configuration
 image:../../../{{book.images}}/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
 
-. Navigate to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/src/main/webapp/WEB-INF* directory and locate the *keycloak.json* file. Replace its contents with the adapter configuration you obtained from step 2 and save the file.
+. Move the file `keycloak.json` to the `app-authz-jee-vanilla/config` directory.
 
 . (optional) By default, the policy enforcer responds with a `403` status code when the user lacks permission to access protected resources on the resource server. However, you can also specify a redirection URL for unauthorized users. To specify a redirection URL, edit the *keycloak.json* file you updated in step 3 and replace the `policy-enforcer` configuration with the following:
 
 ```json
 "policy-enforcer": {
-    "on-deny-redirect-to" : "/hello-world-authz-service/error.jsp"
+    "on-deny-redirect-to" : "/app-authz-vanilla/error.jsp"
   }
 ```
 
-This change specifies to the policy enforcer to redirect users to a `/hello-world-authz-service/error.jsp` page if a user does not have the necessary permissions to access a protected resource, rather than an unhelpful `403 Unauthorized` message.
+This change specifies to the policy enforcer to redirect users to a `/app-authz-vanilla/error.jsp` page if a user does not have the necessary permissions to access a protected resource, rather than an unhelpful `403 Unauthorized` message.
 
 ==== Building and Deploying the Application
 
-To build and deploy the application, navigate to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/* directory and execute the following command:
+To build and deploy the application execute the following command:
 
 ```bash
-mvn clean package wildfly:deploy
+$ cd redhat-sso-quickstarts/app-authz-jee-vanilla
+$ mvn clean package wildfly:deploy
 ```
 
 ==== Testing the Application
 
-If your application was successfully deployed you can access it at http://localhost:8080/hello-world-authz-service[http://localhost:8080/hello-world-authz-service]. The {{book.project.name}} Login page opens.
+If your application was successfully deployed you can access it at http://localhost:8080/app-authz-vanilla[http://localhost:8080/app-authz-vanilla]. The {{book.project.name}} Login page opens.
 
 .Login Page
 image:../../../{{book.images}}/getting-started/hello-world/login-page.png[alt="Login Page"]

topics/getting-started/overview.adoc

@@ -1,21 +1,29 @@
 [[_getting_started_overview]]
 == Getting Started
 
-All tutorials are based on the *{{book.project.name}} Demo Distribution*.
+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 link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.external_link.keycloakinstallingandboot.link}}[{{book.external_link.keycloakinstallingandboot.name}}] 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
+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.
 
-* *keycloak-demo-{{book.project.version}}.[zip|tar.gz]*
+To boot the {{book.project.name}} server:
 
-To unpack this file run the _unzip_ or _gunzip_ and _tar_ utilities. Throughout this guide the directory where you have unpacked
-the demo distribution is referenced as *${KEYCLOAK_DEMO_SERVER_DIR}*.
+.Linux/Unix
+[source]
+----
+$ ${KEYCLOAK_SERVER_DIR}/bin/standalone.sh -Djboss.socket.binding.port-offset=100
+----
 
-[NOTE]
-This guide assumes that you are already familiar with {{book.project.name}} and that you are able to install and boot a {{book.project.name}} Server. For more information, see the link:{{book.project.doc_base_url}}{{book.project.doc_info_version-url}}{{book.external_link.keycloakgettingstarted.link}}[{{book.external_link.keycloakgettingstarted.name}}] tutorials.
+.Windows
+[source]
+----
+> ${KEYCLOAK_SERVER_DIR}\bin\standalone.bat -Djboss.socket.binding.port-offset=100
+----
 
-Ensure you have a {{book.project.name}} instance running; the default configuration is http://localhost:8080/auth[http://localhost:8080/auth]. After logging in to the
-Administration Console, a page similar to this one is displayed:
+For more details about how to install and configure a {{book.appServer}}, please follow the steps on the link:{{book.project.doc_base_url}}{{book.project.doc_info_version_url}}{{book.external_link.keycloakinstallclientadapter.link}}[{{book.external_link.keycloakinstallclientadapter.name}}] tutorial.
 
-.{{book.project.name}} Administration Console
-image:../../{{book.images}}/getting-started/kc-start-page.png[alt="{{book.project.name}} Administration Console"]
-
-All source code for the getting started tutorials can be obtained from the demo distributions. The authorization-related examples
-are located at *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz*.
+After installing and booting both servers you should be able to access {{book.project.name}} Admin Console at http://localhost:8180/auth/admin/ and also the {{book.appServer}} instance at
+http://localhost:8080.