Merge pull request #125 from pedroigor/master

Some updates and fixes

authorization_services/SUMMARY.adoc

@@ -51,6 +51,8 @@
 
    ... link:authorization_services/topics/policy/aggregated-policy.adoc[Aggregated Policy]
 
+   ... link:authorization_services/topics/policy/client-policy.adoc[Client Policy]
+
    ... link:authorization_services/topics/policy/logic.adoc[Positive and Negative Logic]
 
    ... link:authorization_services/topics/policy/evaluation-api.adoc[Policy Evaluation API]

authorization_services/topics/enforcer/authorization-context.adoc

@@ -58,3 +58,14 @@ Although both examples address the same requirements, they do so in different wa
 Now, suppose your security requirements have changed and in addition to project managers, PMOs can also create new projects.
 
 Security requirements change, but with {{book.project.name}} there is no need to change your application code to address the new requirements. Once your application is based on the resource and scope identifier, you need only change the configuration of the permissions or policies associated with a particular resource in the authorization server. In this case, the permissions and policies associated with the `Project Resource` and/or the scope `urn:project.com:project:create` would be changed.
+
+==== Using the AuthorizationContext to obtain an Authorization Client Instance
+
+The ```AuthorizationContext``` can also be used to obtain a reference to the <<fake/../../service/client-api.adoc#_service_client_api, Authorization Client API>> configured to your application:
+
+```java
+    ClientAuthorizationContext clientContext = ClientAuthorizationContext.class.cast(authzContext);
+    AuthzClient authzClient = clientContext.getClient();
+```
+
+In some cases, resource servers protected by the policy enforcer need to access the APIs provided by the authorization server. With an ```AuthzClient``` instance in hands, resource servers can interact with the server in order to create resources or check for specific permissions programmatically.

authorization_services/topics/enforcer/keycloak-enforcement-filter.adoc

@@ -111,6 +111,7 @@ Currently a very basic logic for path matching is supported. Examples of valid p
 **** Sub-paths: `/path/*`
 **** Path parameters: /resource/{id}
 **** Exact match: /resource
+**** Patterns: /{version}/resource, /api/{version}/resource, /api/{version}/resource/*
 +
 *** *methods*
 The HTTP methods (for example, GET, POST, PATCH) to protect and how they are associated with the scopes for a given resource in the server.

authorization_services/topics/policy/aggregated-policy.adoc

@@ -3,7 +3,7 @@
 
 As mentioned previously, {{book.project.name}} allows you to build a policy of policies, a concept referred to as policy aggregation. You can use policy aggregation to reuse existing policies to build more complex ones and keep your permissions even more decoupled from the policies that are evaluated during the processing of authorization requests.
 
-To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the permission listing.
+To create a new aggregated policy, select *Aggregated* in the dropdown list located in the right upper corner of the policy listing.
 
 .Add an Aggregated Policy
 image:../../{{book.images}}/policy/create-aggregated.png[alt="Add Aggregated Policy"]

authorization_services/topics/policy/client-policy.adoc

@@ -0,0 +1,28 @@
+[[_policy_client]]
+=== Client-Based Policy
+
+You can use this type of policy to define conditions for your permissions where a set of one or more clients is permitted to access an object.
+
+To create a new client-based policy, select *Client* in the dropdown list in the upper right corner of the policy listing.
+
+.Add a Client-Based Policy
+image:../../{{book.images}}/policy/create-client.png[alt="Add Client-Based Policy"]
+
+==== Configuration
+
+* *Name*
++
+A human-readable and unique string identifying the policy. A best practice is to use names that are closely related to your business and security requirements, so you
+can identify them more easily.
++
+* *Description*
++
+A string containing details about this policy.
++
+* *Clients*
++
+Specifies which clients are given access by this policy.
++
+* *Logic*
++
+The <<fake/../logic.adoc#_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

authorization_services/topics/policy/drools-policy.adoc

@@ -4,7 +4,7 @@
 With this type of policy you can define conditions for your permissions using http://www.drools.org[Drools], which is a rule evaluation environment. It is one of the _Rule-Based_ policy types
 supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
 
-To create a new Rule-based policy, in the dropdown list in the right upper corner of the permission listing,
+To create a new Rule-based policy, in the dropdown list in the right upper corner of the policy listing,
  select *Rule*.
 
 .Add Rule Policy

authorization_services/topics/policy/js-policy.adoc

@@ -4,7 +4,7 @@
 You can use this type of policy to define conditions for your permissions using JavaScript. It is one of the rule-based policy types
 supported by {{book.project.name}}, and provides flexibility to write any policy based on the <<fake/../evaluation-api.adoc#_policy_evaluation_api, Evaluation API>>.
 
-To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the permission listing.
+To create a new JavaScript-based policy, select *JavaScript* in the dropdown list in the upper right corner of the policy listing.
 
 .Add JavaScript Policy
 image:../../{{book.images}}/policy/create-js.png[alt="Add JavaScript Policy"]

authorization_services/topics/policy/role-policy.adoc

@@ -7,7 +7,7 @@ By default, roles added to this policy are not specified as required and the pol
 
 Role policies can be useful when you need more restricted role-based access control (RBAC), where specific roles must be enforced to grant access to an object. For instance, you can enforce that a user must consent to allowing a client application (which is acting on the user's behalf) to access the user's resources. You can use {{book.project.name}} Client Scope Mapping to enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
 
-To create a new role-based policy, select *Role-Based* in the dropdown list in the upper right corner of the permission listing.
+To create a new role-based policy, select *Role* in the dropdown list in the upper right corner of the policy listing.
 
 .Add Role-Based Policy
 image:../../{{book.images}}/policy/create-role.png[alt="Add Role-Based Policy"]

authorization_services/topics/policy/time-policy.adoc

@@ -3,7 +3,7 @@
 
 You can use this type of policy to define time conditions for your permissions.
 
-To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the permission listing.
+To create a new time-based policy, select *Time* in the dropdown list in the upper right corner of the policy listing.
 
 .Add Time Policy
 image:../../{{book.images}}/policy/create-time.png[alt="Add Time Policy"]

authorization_services/topics/policy/user-policy.adoc

@@ -3,7 +3,7 @@
 
 You can use this type of policy to define conditions for your permissions where a set of one or more users is permitted to access an object.
 
-To create a new user-based policy, select *User-Based* in the dropdown list in the upper right corner of the permission listing.
+To create a new user-based policy, select *User* in the dropdown list in the upper right corner of the policy listing.
 
 .Add a User-Based Policy
 image:../../{{book.images}}/policy/create-user.png[alt="Add User-Based Policy"]

authorization_services/topics/service/client-api.adoc

@@ -1,7 +1,10 @@
 [[_service_client_api]]
 === Authorization Client Java API
 
-If you are using Java, you can access all {{book.project.name}} {{book.project.module}} using a client API.
+Depending on your requirements, a resource server should be able to manage resources remotely or even check for permissions programmatically.
+If you are using Java, you can access the {{book.project.name}} Authorization Services using the Authorization Client API.
+
+It is targeted for resource servers that want to access the different APIs provided by the server such as the Protection, Authorization and Entitlement APIs.
 
 ==== Maven Dependency
 
@@ -17,7 +20,7 @@ If you are using Java, you can access all {{book.project.name}} {{book.project.m
 
 ==== Configuration
 
-The client configuration is defined in a JSON file as follows:
+The client configuration is defined in a ``keycloak.json`` file as follows:
 
 ```json
 {
@@ -43,7 +46,18 @@ The base URL of the {{book.project.name}} server. All other {{book.project.name}
 The client-id of the application. Each application has a client-id that is used to identify the application. 
 
 * *credentials* (required)
-Specifies the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type. Currently only secret/password is supported. 
+Specifies the credentials of the application. This is an object notation where the key is the credential type and the value is the value of the credential type.
+
+The configuration file is usually located in your application's classpath, the default location from where the client is going to try to find a ```keycloak.json``` file.
+
+==== Creating the Authorization Client
+
+Considering you have a ```keycloak.json``` file in your classpath, you can create a new ```AuthzClient``` instance as follows:
+
+```java
+    // create a new instance based on the configuration defined in a keycloak.json located in your classpath
+    AuthzClient authzClient = AuthzClient.create();
+```
 
 ==== Obtaining User Entitlements
 
@@ -55,17 +69,14 @@ AuthzClient authzClient = AuthzClient.create();
 
 // obtain an Entitlement API Token to get access to the Entitlement API.
 // this token is an access token issued to a client on behalf of an user
-// with a scope = kc_entitlement
+// with a uma_authorization scope
 String eat = getEntitlementAPIToken(authzClient);
 
 // send the entitlement request to the server to
 // obtain an RPT with all permissions granted to the user
-EntitlementResponse response = authzClient.entitlement(eat)
-    .getAll("hello-world-authz-service");
+EntitlementResponse response = authzClient.entitlement(eat).getAll("hello-world-authz-service");
 String rpt = response.getRpt();
 
-System.out.println("You got a RPT: " + rpt);
-
 // now you can use the RPT to access protected resources on the resource server
 ```
 
@@ -77,7 +88,7 @@ AuthzClient authzClient = AuthzClient.create();
 
 // obtain an Entitlement API Token to get access to the Entitlement API.
 // this token is an access token issued to a client on behalf of an user
-// with a scope = kc_entitlement
+// with a uma_authorization scope
 String eat = getEntitlementAPIToken(authzClient);
 
 // create an entitlement request
@@ -90,11 +101,10 @@ request.addPermission(permission);
 
 // send the entitlement request to the server to obtain an RPT
 // with all permissions granted to the user
-EntitlementResponse response = authzClient.entitlement(eat)
-    .get("hello-world-authz-service", request);
+EntitlementResponse response = authzClient.entitlement(eat).get("hello-world-authz-service", request);
 String rpt = response.getRpt();
 
-System.out.println("You got a RPT: " + rpt);
+// now you can use the RPT to access protected resources on the resource server
 ```
 
 ==== Creating a Resource Using the Protection API
@@ -112,8 +122,7 @@ newResource.setType("urn:hello-world-authz:resources:example");
 newResource.addScope(new ScopeRepresentation("urn:hello-world-authz:scopes:view"));
 
 ProtectedResource resourceClient = authzClient.protection().resource();
-Set<String> existingResource = resourceClient
-    .findByFilter("name=" + newResource.getName());
+Set<String> existingResource = resourceClient.findByFilter("name=" + newResource.getName());
 
 if (!existingResource.isEmpty()) {
     resourceClient.delete(existingResource.iterator().next());
@@ -126,3 +135,17 @@ String resourceId = response.getId();
 // query the resource using its newly generated id
 ResourceRepresentation resource = resourceClient.findById(resourceId).getResourceDescription();
 ```
+
+==== Introspecting a RPT
+
+```java
+    AuthzClient authzClient = AuthzClient.create();
+    String rpt = getRequestingPartyToken(authzClient);
+    TokenIntrospectionResponse requestingPartyToken = authzClient.protection().introspectRequestingPartyToken(rpt);
+
+    if (requestingPartyToken.getActive()) {
+        for (Permission granted : requestingPartyToken.getPermissions()) {
+            // iterate over the granted permissions
+        }
+    }
+```