From e480943bc466dc04968586ea668ee1f99568a6b3 Mon Sep 17 00:00:00 2001 From: Pedro Igor Date: Tue, 7 Jun 2016 19:15:14 -0300 Subject: [PATCH] More docs --- SUMMARY.adoc | 3 +- ...ntitlement-bearer-enforcement-filter.adoc} | 18 +- .../uma-bearer-enforcement-filter.adoc | 177 ++++++++++++++++++ 3 files changed, 193 insertions(+), 5 deletions(-) rename topics/enforcer/{bearer-enforcement-filter.adoc => entitlement-bearer-enforcement-filter.adoc} (80%) create mode 100755 topics/enforcer/uma-bearer-enforcement-filter.adoc diff --git a/SUMMARY.adoc b/SUMMARY.adoc index 4ff26da77d..ce4df5a7cb 100755 --- a/SUMMARY.adoc +++ b/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] \ No newline at end of file diff --git a/topics/enforcer/bearer-enforcement-filter.adoc b/topics/enforcer/entitlement-bearer-enforcement-filter.adoc similarity index 80% rename from topics/enforcer/bearer-enforcement-filter.adoc rename to topics/enforcer/entitlement-bearer-enforcement-filter.adoc index a77943ddbb..b04f392d53 100755 --- a/topics/enforcer/bearer-enforcement-filter.adoc +++ b/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 Keycloak Authorization Enforcer - org.keycloak.authorization.policy.enforcer.servlet.BearerTokenEnforcementFilter + org.keycloak.authorization.policy.enforcer.servlet.EntitlementBearerTokenEnforcementFilter @@ -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 { diff --git a/topics/enforcer/uma-bearer-enforcement-filter.adoc b/topics/enforcer/uma-bearer-enforcement-filter.adoc new file mode 100755 index 0000000000..0963c473b3 --- /dev/null +++ b/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 + + Keycloak Authorization Enforcer + org.keycloak.authorization.policy.enforcer.servlet.UmaBearerTokenEnforcementFilter + + + + Keycloak Authorization Enforcer + /* + +``` + +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 + + + + + + + + + + +