diff --git a/SUMMARY.adoc b/SUMMARY.adoc index c6d20c83e6..9ff55b74d5 100755 --- a/SUMMARY.adoc +++ b/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] @@ -46,5 +47,4 @@ .. link:topics/enforcer/keycloak-enforcement-filter.adoc[Keycloak Adapter Policy Enforcer] ... 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] \ No newline at end of file + ... link:topics/enforcer/js-adapter.adoc[JavaScript Integration] \ No newline at end of file diff --git a/images/resource-server/authz-export.png b/images/resource-server/authz-export.png index 41a94f9e89..59a1dd6bb3 100644 Binary files a/images/resource-server/authz-export.png and b/images/resource-server/authz-export.png differ diff --git a/images/resource-server/authz-settings.png b/images/resource-server/authz-settings.png index 9b3aaa6084..6fb147b140 100644 Binary files a/images/resource-server/authz-settings.png and b/images/resource-server/authz-settings.png differ diff --git a/topics/example/overview.adoc b/topics/example/overview.adoc index 4488a0c1b4..2d0cd4561a 100755 --- a/topics/example/overview.adoc +++ b/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. \ No newline at end of file +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. +|=== \ No newline at end of file diff --git a/topics/policy/drools-policy.adoc b/topics/policy/drools-policy.adoc index cc4479d578..af25d0d477 100644 --- a/topics/policy/drools-policy.adoc +++ b/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. diff --git a/topics/policy/evaluation-api.adoc b/topics/policy/evaluation-api.adoc index b4c7e3cdd2..41a6ce3ce2 100755 --- a/topics/policy/evaluation-api.adoc +++ b/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 -can obtain useful information. +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 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. -* Information about the runtime environment and any other attribute associated with the execution context. +* The permission being requested +* 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 -+ -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 -to a oAuth2 Access Token you can also access this claim from a policy and use it to build your conditions -+ -* Some built-in environment attributes such as: -+ -** kc.authz.context.time.date_time, holding the current time -** kc.authz.context.client.network.ip_address, holding the IP address of the client requesting permissions -** kc.authz.context.client.network.host, holding the host name of the client requesting permissions +The `EvaluationContext` also gives you access to attributes related with both execution and runtime environment. For now, there only a few built-in attributes. + +.Execution and Runtime Attributes +|=== +|Name |Description | Type + +| kc.time.date_time +| Current date and time +| String. Format `MM/dd/yyyy hh:mm:ss` + +| 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 + +|=== diff --git a/topics/policy/js-policy.adoc b/topics/policy/js-policy.adoc index c6fc299147..cd99768b2d 100644 --- a/topics/policy/js-policy.adoc +++ b/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(); } ``` diff --git a/topics/resource-server/default-config.adoc b/topics/resource-server/default-config.adoc index 281dc95291..438182f94a 100755 --- a/topics/resource-server/default-config.adoc +++ b/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();