Merge pull request #9 from pedroigor/master

More docs

SUMMARY.adoc

@@ -44,5 +44,6 @@
  .. link:topics/service/client-api.adoc[Authorization Client Java API]
  . link:topics/enforcer/overview.adoc[Policy Enforcers]
  .. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Servlet Policy Enforcer]
- .. link:topics/enforcer/bearer-enforcement-filter.adoc[Bearer Token Servlet Policy Enforcer]
+ .. link:topics/enforcer/entitlement-bearer-enforcement-filter.adoc[Entitlement Bearer Token Servlet Policy Enforcer]
+ .. link:topics/enforcer/uma-bearer-enforcement-filter.adoc[UMA Bearer Token Servlet Policy Enforcer]
  . link:topics/example/overview.adoc[Examples]

topics/enforcer/entitlement-bearer-enforcement-filter.adoc

@@ -1,6 +1,6 @@
-== Bearer Token Enforcement Filter
+== Entitlement Bearer Token Enforcement Filter
 
-The *org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter* can be used to protect servlet applications providing
+The *org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter* can be used to protect servlet applications providing
 RESTful services. For instance, applications using JAX-RS.
 
 This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
@@ -10,7 +10,7 @@ To configure it, change your web application descriptor (WEB-INF/web.xml) as fol
 ```xml
 <filter>
     <filter-name>Keycloak Authorization Enforcer</filter-name>
-    <filter-class>org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter</filter-class>
+    <filter-class>org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter</filter-class>
 </filter>
 
 <filter-mapping>
@@ -27,9 +27,19 @@ curl -X GET \
     "http://my-app/api/resource"
 ```
 
+If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
+a *WWW-Authenticate* header as follows:
+
+```bash
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: KC_ETT realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/entitlement"
+```
+
+Where *KC_ETT* indicates that the resource server requires a RPT with entitlements and *as_uri* holds the URI that clients can use to obtain a RPT based on an OAuth2 Access Token previously issued by a {{book.project.name}} server during user authentication.
+
 === Configuration
 
-The BearerTokenEnforcementFilter can be configured by a simple JSON file. The file can be as simple as:
+The _EntitlementBearerTokenEnforcementFilter_ can be configured by a simple JSON file. The file can be as simple as:
 
 ```json
 {

topics/enforcer/uma-bearer-enforcement-filter.adoc

@@ -0,0 +1,177 @@
+== UMA Bearer Token Enforcement Filter
+
+The *org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter* can be used to protect servlet applications providing
+RESTful services. For instance, applications using JAX-RS.
+
+This filter does not require that your application is configured with any {{book.project.name}} OIDC Adapter.
+
+To configure it, change your web application descriptor (WEB-INF/web.xml) as follows:
+
+```xml
+<filter>
+    <filter-name>Keycloak Authorization Enforcer</filter-name>
+    <filter-class>org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter</filter-class>
+</filter>
+
+<filter-mapping>
+    <filter-name>Keycloak Authorization Enforcer</filter-name>
+    <url-pattern>/*</url-pattern>
+</filter-mapping>
+```
+
+When using this filter, client applications need to send a RPT as a *Bearer* token using the *Authorization* header in order to gain access to a protected resource.
+
+```bash
+curl -X GET \
+    -H "Authorization: Bearer %{RPT}" \
+    "http://my-app/api/resource"
+```
+
+If the client application (or requesting party) trying to access the protected resource does not provide a RPT within the request, the filter is going to respond to the client with a 401 HTTP status code and
+a *WWW-Authenticate* header as follows:
+
+```bash
+HTTP/1.1 401 Unauthorized
+WWW-Authenticate: UMA realm="${resource_server_id}",as_uri="http://${kc_server_host}:${kc_server_port}/auth/realms/${realm_name}/authz/authorize",ticket="${PERMISSION_TICKET}"
+```
+
+From that response, users can use the permission ticket returned by the resource server and use it to obtain a RPT using the UMA protocol, as described by link:../service/authorization/authorization-api.html[Authorization API].
+
+Where *UMA* indicates that this resource server requires a RPT and *as_uri* holds the URI that clients can use to obtain the RPT based on UMA protocol.
+
+=== Configuration
+
+The _EntitlementBearerTokenEnforcementFilter_ can be configured by a simple JSON file. The file can be as simple as:
+
+```json
+{
+  "client": {
+    "configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
+    "clientId": "{client_id}",
+    "clientSecret": "{client_secret}"
+  },
+  "enforcer": {
+    "user-managed-access": {}
+  }
+}
+```
+Or a little more verbose if you want to manually define the resources being protected:
+
+```json
+{
+  "client": {
+    "configurationUrl": "http://localhost:8080/auth/realms/{realm_name}/authz/uma_configuration",
+    "clientId": "{client_id}",
+    "clientSecret": "{client_secret}"
+  },
+  "enforcer": {
+    "user-managed-access": {},
+    "paths": [
+      {
+        "path" : "/someUri/*",
+        "methods" : [
+          {
+            "method": "GET",
+            "scopes" : ["urn:app.com:scopes:view"]
+          },
+          {
+            "method": "POST",
+            "scopes" : ["urn:app.com:scopes:create"]
+          }
+        ]
+      },
+      {
+        "name" : "Some Resource",
+        "path" : "/usingPattern/{id}",
+        "methods" : [
+          {
+            "method": "DELETE",
+            "scopes" : ["urn:app.com:scopes:delete"]
+          }
+        ]
+      },
+      {
+        "path" : "/exactMatch"
+      },
+      {
+        "name" : "Admin Resources",
+        "path" : "/usingWildCards/*"
+      }
+    ]
+  }
+}
+```
+
+The file with the enforcer configuration must be under your application's classpath as *keycloak-authz.json".
+
+Here is a description of each configuration option:
+
+* *client*
++
+Specify the information about the resource server being protected
++
+** *configurationUrl*
++
+A URL pointing to a configuration endpoint. This is important for the automatic discovery of the services invoked during the authorization process.
++
+** *clientId*
++
+The id of the client acting as a resource server.
++
+** *clientSecret*
++
+The client secret.
++
+* *enforcer*
++
+Specify the configuration options to define how policies are actually enforced and optionally the paths you want to protect. If empty, the policy enforcer will query the server
+for all resources associated with the resource server being protected. In this case, you need to make sure the resources are properly configured with a *uri* property that matches the paths
+ you want to protect.
++
+** *paths*
++
+Specify the paths to protect.
++
+*** *name*
++
+The name of a resource in the server that must be associated with a given path. If provided, the policy enforcer will ignore the resource's *uri* property and use the path you provided.
+*** *path*
++
+A URI relative to the application's context path. If this option is provided, the policy enforcer will query the server for a resource with a *uri* with the same value.
+Right now, we support some very basic logic for path matching. Examples of valid paths are:
++
+**** Wildcards: `/*`
+**** Suffix: `/*.html`
+**** Sub-paths: `/path/*`
+**** Path parameters: /resource/{id}
+**** Exact match: /resource
++
+*** *methods*
+The HTTP methods to protect and how they are associated with the scopes for a given resource in the server.
++
+**** *method*
++
+The name of the HTTP method.
++
+**** *scopes*
++
+An array of strings with the scopes associated with the method.
+
+=== Container Specific Configuration
+
+==== WildFly 10.0.0.Final
+
+In order to make the filter available to your application at runtime, you must create a *META-INF/jboss-deployment-structure.xml* at the application root directory.
+
+```xml
+<jboss-deployment-structure>
+    <deployment>
+        <dependencies>
+            <module name="org.keycloak.keycloak-authz-servlet-enforcer" services="import"/>
+            <module name="org.jboss.resteasy.resteasy-jackson2-provider" services="import"/>
+        </dependencies>
+        <exclusions>
+            <module name="org.jboss.resteasy.resteasy-jackson-provider"/>
+        </exclusions>
+    </deployment>
+</jboss-deployment-structure>