Merge pull request #22 from pedroigor/master

Minor fixes and updates

SUMMARY.adoc

@@ -8,6 +8,7 @@
  ... 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/example/overview.adoc[Examples]
  . 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]
@@ -47,4 +48,3 @@
  ... link:topics/enforcer/keycloak-enforcement-bearer.adoc[Protecting a Stateless Service Using a Bearer Token]
  ... link:topics/enforcer/authorization-context.adoc[Obtaining the Authorization Context]
  ... link:topics/enforcer/js-adapter.adoc[JavaScript Integration]
- . link:topics/example/overview.adoc[Examples]

topics/example/overview.adoc

@@ -1,5 +1,34 @@
 == Examples
 
-We provide a few examples about how to use the {{book.project.name}} {{book.project.module}}. These examples are very useful to understand the concepts here introduced.
+The {{book.project.name}} Authorization can also help you to quickly get started with the authorization services and understand how to apply the same concepts to your
+own applications.
 
-The examples are located at *examples/authz*. They contain a README.md file with more details about how to build and deploy them.
+If you are using the {{book.project.name}} Demo Distribution and you have it properly extracted in your filesystem:
+
+* **keycloak-demo-{{book.project.version}}.[zip|tar.gz]**
+
+You can check out the available examples from the following directory:
+
+```bash
+cd ${KEYCLOAK_DEMO_SERVER_DIR}/examples/authz
+```
+
+Or you can get them from https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz[GitHub].
+
+For each example is provided a `README` file with instructions about how to build, deploy and test the example.
+
+Here is a brief description of each of them:
+
+.Authorization Examples
+|===
+|Name |Description
+
+| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[hello-world-authz-service]
+| A single page application which is protected by a policy enforcer that decides whether an user can access that page or not based on the permissions obtained from a Keycloak Server.
+
+| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[photoz]
+| A simple application based on HTML5+AngularJS+JAX-RS that demonstrates how to enable fine-grained permissions to RESTFul based services and HTML5 clients.
+
+| https://github.com/keycloak/keycloak/tree/{{book.project.version}}/examples/authz/servlet-authz[servlet-authz]
+| A simple Servlet-based application that demonstrates how to enable fine-grained authorization to a JBoss Servlet Application.
+|===

topics/policy/drools-policy.adoc

@@ -1,7 +1,7 @@
 == Drools-Based Policy
 
 This type of policy allows you to define conditions for your permissions using Drools. It is one of the _Rule-Based_ policy types
-supported by {{book.project.name}}, providing a lot of flexibility to write any policy based on the link::/policy/evaluation-api.adoc[Evaluation API].
+supported by {{book.project.name}}, providing a lot of flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
 
 To create a new policy select the option *Drools* in the dropdown located in the right upper corner of the permission listing.
 

topics/policy/evaluation-api.adoc

@@ -1,12 +1,13 @@
 == Evaluation API
 
-When writing rule-based policies such as when you are using Javascript or JBoss Drools, Keycloak provides an *Evaluation API* from where you
+When writing rule-based policies such as when you are using Javascript or JBoss Drools, {{book.project.name}} provides an *Evaluation API* from where you
-can obtain useful information.
+can obtain useful information in order to decide whether a permission should be granted or not.
 
 This API consists of a few interfaces that provides you access to information such as:
 
-* Information about the identity asking for a permission. Here you can obtain the identity identifier (eg.: username) or any other claim/attribute about it.
+* The permission being requested
-* Information about the runtime environment and any other attribute associated with the execution context.
+* The identity asking for a permission, from where you can obtain claims/attributes
+* Runtime environment and any other attribute associated with the execution context
 
 The main interface is *org.keycloak.authorization.policy.evaluation.Evaluation*, which defines the following contract:
 
@@ -38,8 +39,14 @@ public interface Evaluation {
     void deny();
 }
 ```
+[NOTE]
+For more details about the Evaluation API refer to http://www.keycloak.org/docs/javadocs/index.html[JavaDocs].
 
-For full instructions on using the Evaluation API refer to JavaDocs.
+When processing an authorization request, {{book.project.name}} creates an `Evaluation` instance before evaluating any policy. This instance is then passed to each policy in order to obtain
+a decision, which would be a *GRANT* or a *DENY*.
+
+Policies take their decisions by invoking the `grant()` or `deny()` methods on an `Evaluation` instance. By default, the state of the `Evaluation` instance is denied, which means that your policies
+need to explicitly invoke the `grant()` method if they want to tell the policy evaluation engine that the permission should be granted.
 
 === The Evaluation Context
 
@@ -66,18 +73,41 @@ public interface EvaluationContext {
 
 From this interface, policies can obtain:
 
-* The authenticated *Identity*
+* The authenticated `Identity`
 * Information about the execution context and runtime environment
 
-Before evaluating policies, {{book.project.name}} builds an *EvaluationContext* based on:
+The `Identity` is built based on the OAuth2 Access Token that was sent along with the authorization request, from where you have access to all claims
+extracted from the original token. For instance, if you are using a _Protocol Mapper_ to include a custom claim to a oAuth2 Access Token you can also access this claim
+from a policy and use it to build your conditions
 
-* All claims obtained from the OAuth2 Access Token that was sent along with the authorization request
+The `EvaluationContext` also gives you access to attributes related with both execution and runtime environment. For now, there only a few built-in attributes.
-+
+
-In this case, the *Identity* object provides the same claims as define by the access token. For instance, if you are using a _Protocol Mapper_ to include custom claim
+.Execution and Runtime Attributes
-to a oAuth2 Access Token you can also access this claim from a policy and use it to build your conditions
+|===
-+
+|Name |Description | Type
-* Some built-in environment attributes such as:
+
-+
+| kc.time.date_time
-** kc.authz.context.time.date_time, holding the current time
+| Current date and time
-** kc.authz.context.client.network.ip_address, holding the IP address of the client requesting permissions
+| String. Format `MM/dd/yyyy hh:mm:ss`
-** kc.authz.context.client.network.host, holding the host name of the client requesting permissions
+
+| kc.client.network.ip_address
+| IPv4 address of the client
+| String
+
+| kc.client.network.host
+| Client's host name
+| String
+
+| kc.client.id
+| The client id
+| String
+
+| kc.client.user_agent
+| The value of the 'User-Agent' HTTP header
+| String[]
+
+| kc.realm.name
+| The name of the realm
+| String
+
+|===

topics/policy/js-policy.adoc

@@ -1,7 +1,7 @@
 == JavaScript-Based Policy
 
 This type of policy allows you to define conditions for your permissions using JavaScript. It is one of the _Rule-Based_ policy types
-supported by {{book.project.name}}, providing lot of flexibility to write any policy based on the link::/policy/evaluation-api.adoc[Evaluation API].
+supported by {{book.project.name}}, providing lot of flexibility to write any policy based on the link:evaluation-api.adoc[Evaluation API].
 
 To create a new policy select the option *JavaScript* in the dropdown located in the right upper corner of the permission listing.
 
@@ -36,7 +36,7 @@ obtained from the execution context:
 var context = $evaluation.getContext();
 var contextAttributes = context.getAttributes();
 
-if (contextAttributes.containsValue('kc.authz.context.client.network.ip_address', '127.0.0.1')) {
+if (contextAttributes.containsValue('kc.client.network.ip_address', '127.0.0.1')) {
     $evaluation.grant();
 }
 ```

topics/resource-server/default-config.adoc

@@ -31,7 +31,7 @@ var context = $evaluation.getContext();
 
 // using attributes from the evaluation context to obtain the realm
 var contextAttributes = context.getAttributes();
-var realmName = contextAttributes.getValue('kc.authz.context.authc.realm').asString(0);
+var realmName = contextAttributes.getValue('kc.realm.name').asString(0);
 
 // using attributes from the identity to obtain the issuer
 var identity = context.getIdentity();