Getting started

SUMMARY.adoc

@@ -2,7 +2,12 @@
 
  . link:topics/overview/overview.adoc[Overview]
  .. link:topics/overview/architecture.adoc[Architecture]
-  .. link:topics/overview/terminology.adoc[Terminology]
+ .. link:topics/overview/terminology.adoc[Terminology]
+ . link:topics/getting-started/overview.adoc[Getting Started]
+ .. link:topics/getting-started/hello-world/overview.adoc[Securing a Servlet Application]
+ ... link:topics/getting-started/hello-world/create-realm.adoc[Creating a Realm]
+ ... 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]
  . link:topics/resource-server/overview.adoc[Managing Resource Servers]
  .. link:topics/resource-server/create-client.adoc[Creating a Client Application]
  .. link:topics/resource-server/enable-authorization.adoc[Enabling Authorization Services]

book.json

@@ -15,7 +15,7 @@
     "images": "keycloak-images",
     "project": {
       "name": "Keycloak",
-      "version": "1.9.3.Final-SNAPSHOT",
+      "version": "2.0.0.CR1-SNAPSHOT",
       "module": "Authorization Services"
     }
   }

topics/enforcer/keycloak-enforcement-filter.adoc

@@ -26,6 +26,7 @@ Or a little more verbose if you want to manually define the resources being prot
 {
   "policy-enforcer": {
     "user-managed-access" : {},
+    "enforcement-mode" : "ENFORCING"
     "paths": [
       {
         "path" : "/someUri/*",
@@ -75,6 +76,22 @@ for all resources associated with the resource server being protected. In this c
 Tells the adapter to use the UMA protocol. If set, the adapter will ask the server for permission tickets and return them to clients accordingly with UMA specification. If not set,
 the adapter will just rely on the RPT sent to the server to actually enforce permissions.
 +
+** *enforcement-mode*
++
+Dictates how policies are enforced.
++
+*** *ENFORCING*
++
+This is the default mode. Requests are denied by default even when there is no policy associated with a given resource.
++
+*** *PERMISSIVE*
++
+Requests are allowed even when there is no policy associated with a given resource.
++
+*** *DISABLED*
++
+Completely disables the evaluation of policies and allow access to any resource.
++
 ** *paths*
 +
 Specify the paths to protect.

topics/getting-started/hello-world/before-start.adoc

@@ -0,0 +1,13 @@
+== Before You Start
+
+This guide is based on the *{{book.project.name}} Demo Distribution*. Please download it before going further with any guide.
+
+[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, please follow the intrusctions https://keycloak.gitbooks.io/getting-started-tutorials/content/[here].
+
+Make sure you have a {{book.project.name}} instance up and running on http://localhost:8080/auth[http://localhost:8080/auth]. If everything is OK, you should be able to login to the
+_Administration Console_ and get a page like that:
+
+image:../../images/gs-keycloak-console-page.png[alt="Keycloak Administration Console"]
+
+Source code for all examples can be obtained from *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/*.

topics/getting-started/hello-world/create-realm.adoc

@@ -0,0 +1,29 @@
+== Creating a Realm
+
+The first step is to create a realm. The realm we are about to create is very simple and consists of:
+
+* A single user
+
+* A single client application, which we're going to turn into a link:../../overview/terminology.html[Resource Server] and enable
+the authorization services
+
+Create a realm with a name *hello-world-authz*. Once created, you should be able to see a page like that.
+
+.Realm hello-world-authz
+image:../../../images/getting-started/hello-world/create-realm.png[alt="Realm hello-world-authz"]
+
+After creating the realm, you should also create a single user. For that, click on the `Users` left menu item. This will bring 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 the new user.
+
+Fill in the fields as shown below and click `Save`.
+
+.Add User
+image:../../../images/getting-started/hello-world/create-user.png[alt="Add User"]
+
+Let's set a password for the *alice* user. Click on the `Credentials` tab. This will bring you to the `Credentials` page.
+
+.Set User Password
+image:../../../images/getting-started/hello-world/reset-user-pwd.png[alt="Set User Password"]
+
+Fill in the `New Password` and `Password Confirmation` fields with a password and click on the `Temporary` switch to turn it `OFF`. For last,
+click on the `Reset Password` button to reset the user's password.

topics/getting-started/hello-world/create-resource-server.adoc

@@ -0,0 +1,25 @@
+== Enabling Authorization Services
+
+You can enable authorization services to any existing client application using the OpenID Connect Protocol. However, in this guide we are
+going to create a new one from scratch.
+
+Click on the `Clients` left menu item to start creating a new client application and fill in the fields as shown below:
+
+.Create Client Application
+image:../../../images/getting-started/hello-world/create-client.png[alt="Create Client Application"]
+
+Click on the `Save` button to create the client. This should bring you the `Client Details` page.
+
+.Client Details
+image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
+
+In this page, click on the `Authorization Services Enabled` button. When you do that, a new `Authorization` tab will show up.
+Click on this tab and you should see a page like that.
+
+.Authorization Settings
+image:../../../images/getting-started/hello-world/authz-settings.png[alt="Authorization Settings"]
+
+When you enable authorization services to a client application, {{book.project.name}} defines some link:../../resource-server/default-config.html[Default Settings] to
+your application.
+
+For more details about authorization configuration, please take a look at link:../../resource-server/enable-authorization.html[Enabling Authorization Services].

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

@@ -0,0 +1,48 @@
+== Build, Deploy and Test
+
+Now that the *hello-world-authz-service* is properly configured and authorization services are enabled, we can deploy it to
+the server and see the results.
+
+=== Generating the Adapter Configuration
+
+First, let's obtain the adapter configuration from the {{book.project.name}} Administration Console. Click on the `Clients` left menu item. In the client listing,
+click on the *hello-world-authz-service* client application. This you bring you the `Client Details` page.
+
+.Client Details
+image:../../../images/getting-started/hello-world/enable-authz.png[alt="Client Details"]
+
+Click on the `Installation Tab`. In this tab select `Keycloak OIDC JSON` as the format option. This will bring you the adapter config using a JSON format.
+
+.Adapter Configuration
+image:../../../images/getting-started/hello-world/adapter-config.png[alt="Adapter Configuration"]
+
+Now, go to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/src/main/webapp*. There you'll find a *keycloak.json* file. Replace its contents with the adapter configuration
+you just obtained from the {{book.project.name}} Administration Console.
+
+=== Build and Deploy the Application
+
+For last, got to the *${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz/hello-world-authz-service/* and execute the following command:
+
+```bash
+mvn clean package wildfly:deploy
+```
+
+=== Test the Application
+
+If your application was successfully deployed you should be able to access it at http://localhost:8080/hello-world-authz-service[http://localhost:8080/hello-world-authz-service].
+
+The first page you should see is the {{book.project.name}} Login Page.
+
+.Login Page
+image:../../../images/getting-started/hello-world/login-page.png[alt="Login Page"]
+
+Try to login as *alice*. After the authentication you should see a page as follows:
+
+.Hello World Authz Main Page
+image:../../../images/getting-started/hello-world/main-page.png[alt="Hello World Authz Main Page"]
+
+The link:../../resource-server/default-config.html[Default Settings] defined by {{book.project.name}} when you enable authorization services to a client application provides a simple
+policy that only grants access to users belonging to the realm of the client.
+
+You can start playing around by changing the default permissions and policies and check how your application will behave. Or even create new policies using the different
+link:../../policy/overview.html[Policy Types] provided by {{book.project.name}}.

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

@@ -0,0 +1,12 @@
+== Hello World
+
+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 authorization features provided by {{book.project.name}}.
+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 sections in this documentation.
+
+From this guide you'll understand some key concepts around {{book.project.name}} {{book.project.module}}:
+
+* How to enable fine-grained authorization to a client application ?
+* How to turn a client application into a resource server, whose resources are protected ?
+* How to define permissions and authorization policies to govern access to the protected resources ?
+* How to enable policy enforcement to your application ?

topics/getting-started/overview.adoc

@@ -0,0 +1,20 @@
+== Getting Started
+
+All tutorials are based on the *{{book.project.name}} Demo Distribution*.
+
+* *keycloak-demo-{{book.project.version}}.[zip|tar.gz]*
+
+To unpack this file run the _unzip_ or _gunzip_ and _tar_ utilities. During this guide we'll reference the directory you have unpacked
+the demo distribution as *${KEYCLOAK_DEMO_SERVER_DIR}*.
+
+[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, please follow the intrusctions https://keycloak.gitbooks.io/getting-started-tutorials/content/[here].
+
+Make sure you have a {{book.project.name}} instance up and running on http://localhost:8080/auth[http://localhost:8080/auth]. If everything is OK, you should be able to login to the
+_Administration Console_ and get a page like that:
+
+.{{book.project.name}} Administration Console
+image:../../images/getting-started/kc-start-page.png[alt="Keycloak 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*.