Merge pull request #24 from pedroigor/master

Fixes based on Stian feedback.

SUMMARY.adoc

@@ -28,6 +28,7 @@
  .. link:topics/policy/evaluation-api.adoc[Policy Evaluation API]
  . link:topics/permission/overview.adoc[Managing Permissions]
  .. link:topics/permission/create-resource.adoc[Creating Resource-based Permissions]
+ ... link:topics/permission/typed-resource-permission.adoc[Typed Resource Permissions]
  .. link:topics/permission/create-scope.adoc[Creating Scope-based Permissions]
  .. link:topics/permission/decision-strategy.adoc[Policy Decision Strategies]
  . link:topics/policy-evaluation-tool/overview.adoc[Evaluating and Testing Policies]

topics/enforcer/keycloak-enforcement-filter.adoc

@@ -123,4 +123,5 @@ The name of the HTTP method.
 +
 **** *scopes*
 +
-An array of strings with the scopes associated with the method.
+An array of strings with the scopes associated with the method. When you associate scopes with a specific method, the client trying to access a protected resource (or path) must provide
+a RPT that grants permission to all scopes here specified.

topics/getting-started/hello-world/deploy.adoc

@@ -56,4 +56,28 @@ The link:../../resource-server/default-config.html[Default Settings] defined by
 policy that only grants access to users belonging to the realm of the client.
 
 You can start playing around by changing the default permissions and policies and check how your application will behave. Or even create new policies using the different
-link:../../policy/overview.html[Policy Types] provided by {{book.project.name}}.
+link:../../policy/overview.html[Policy Types] provided by {{book.project.name}}.
+
+There are a plenty of things you can do now to test this application. For instance, try to change the `Default Policy` as follows:
+
+```js
+// let's see what happens when we call $evaluation.deny()
+$evaluation.grant();
+
+```
+
+Now, try to logout from the application and log in again. You should no longer be able to access the application.
+
+image:../../../images/getting-started/hello-world/access-denied-page.png[alt="Access Denied Page"]
+
+Let's fix that now, but instead of changing the `Default Policy` code we are just going to change the `Logic` to `Negative`. That should bring back access to the application
+as we are just negating the result of that policy, which is by default denying all requests for access. Again, before testing this change, please logout and log in again.
+
+=== Next Steps
+
+There are a lot of other things you can do from now on, such as:
+
+* Create a scope, define a policy and permission for it and check on the application side if the user is allowed to perform some action (or anything else represented by the scope you created)
+* Create different types of policies such as link:../../policy/role-policy.adoc[Role-Based], link:../../policy/user-policy.adoc[User-Based], link:../../policy/time-policy.adoc[Time-Based], link:../../policy/aggregated-policy.adoc[Aggregated Policies], link:../../policy/drools-policy.adoc[Drools-Based]. And associate these policies with the `Default Permission`
+* Apply multiple policies to the `Default Permission` and check behavior. For instance, try to mix multiple policies and change the `Decision Strategy` accordingly
+* Checkout the link:../../enforcer/authorization-context.adoc[Obtaining the Authorization Context] topic for more details about how to check for permissions inside your application

topics/overview/architecture.adoc

@@ -7,13 +7,13 @@ From a design perspective, the {{book.project.module}} are based on a well defin
 * **Policy Administration Point (PAP)**
 +
 Provides a set of UIs based on {{book.project.name}} Administration Console to manage resource servers, resources, scopes, permissions and policies.
-Part of this also accomplished remotely through the use of the link:../service/protection-api.html[Protection API].
+Part of this also accomplished remotely through the use of the link:../service/protection/protection-api.adoc[Protection API].
 +
 
 * **Policy Decision Point (PDP)**
 +
 Provides a distributable policy decision point to where authorization requests are sent and policies are evaluated accordingly with the permissions being requested. Part of this also accomplished remotely through the use of the
-link:../service/authorization-api.html[Authorization] and link:../service/entitlement-api.html[Entitlement] APIs.
+link:../service/authorization/authorization-api.adoc[Authorization] and link:../service/entitlement/entitlement-api.adoc[Entitlement] APIs.
 +
 
 * **Policy Enforcement Point (PEP)**
@@ -52,7 +52,7 @@ A Resource can be a web page, a RESTFul resource, a file in your filesystem, an
 For instance, you may have a _Bank Account_ resource that represents all banking accounts and use it to define the authorization policies that are common to all banking accounts. However,
 you may want to define specific policies for _Alice Account_ (a resource instance that belongs to a customer), where only the owner is allowed to access some information or perform an operation.
 
-Resources can be managed using {{book.project.name}} Administration Console or the link:../service/protection-api.html[Protection API]. In the latter case, resource servers are able to
+Resources can be managed using {{book.project.name}} Administration Console or the link:../service/protection/protection-api.adoc[Protection API]. In the latter case, resource servers are able to
 manage their resources remotely.
 
 Scopes usually represent the actions that can be performed on a resource, but they are not limited to that. You can also use scopes to represent a single or multiple attributes within a resource.
@@ -120,11 +120,11 @@ When using the UMA protocol, the issuance of Permission Tickets by the Protectio
 being requested by client and that are sent to the server in order to obtain a final token with all permissions granted during the evaluation of the permissions and policies
 associated with the resources and scopes being requested.
 
-For more information, see link:../service/protection-api.html[Protection API].
+For more information, see link:../service/protection/protection-api.adoc[Protection API].
 
 ==== Authorization API
 
-The *Authorization API* is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an ID Token and _Permission Ticket_
+The *Authorization API* is also a https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA-compliant] endpoint providing a single operation that exchanges an Access Token and link:./terminology.adoc#_permission_ticket[Permission Ticket].
 with a *Requesting Party Token* or *RPT*.
 
 The RPT holds all permissions granted to a client and can be used to call a resource server in order to get access to its protected resources.
@@ -134,18 +134,18 @@ within a permission ticket.
 
 image:../../images/authz-calls.png[alt="Authorization API Overview"]
 
-For more information, see link:../service/authorization-api.html[Authorization API].
+For more information, see link:../service/authorization/authorization-api.adoc[Authorization API].
 
 === Entitlement API
 
-The *Entitlement API* provides a 1-legged protocol to issue RPTs. Unlike the _Authorization API_, the Entitlement API only expects an ID Token.
+The *Entitlement API* provides a 1-legged protocol to issue RPTs. Unlike the _Authorization API_, the Entitlement API only expects an Access Token.
 
 From this API you can obtain all the entitlements or permissions for an user (based on the resources managed by a given resource server) or just the entitlements for a set of
 one or more resources.
 
 image:../../images/entitlement-calls.png[alt="Entitlement API Overview"]
 
-For more informationm, see link:../service/entitlement-api.html[Entitlement API].
+For more informationm, see link:../service/entitlement/entitlement-api.adoc[Entitlement API].
 
 
 

topics/overview/terminology.adoc

@@ -72,4 +72,18 @@ so you can create individual policies, reuse them on different permissions and b
 Policy providers are responsible to support a specific policy type. Although {{book.project.name}} provides some built-in policies, backed by their corresponding
 policy providers, nothing stops you to create your own policy types in order to better support your requirements or a specific use case.
 
-{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug your own policy providers.
+{{book.project.name}} provides a *SPI* (Service Provider Interface) that you can use to plug your own policy providers.
+
+[[_permission_ticket]]
+==== Permission Ticket
+
+A Permission Ticket is a special type of token defined by the https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification that provides an opaque structure whose form is determined by the authorization server. This
+structure represents the resources and/or scopes being requested by a client as well the policies that must be applied to a request for authorization data (RPT).
+
+In UMA, permission tickets are crucial to support *person-to-person sharing* and also *person-to-organization sharing*, introducing the possbility to cover from the most simple to the most complex
+*authorization workflows*, where resource owners and resource servers may have complete control over their resources based on fine-grained policies that govern the access to these resources.
+
+During the UMA flow, permissions tickets are issued by the authorization server to a resource server, which in turn returns it back to the client trying to access a protected resource. Once the client
+ receives the ticket, it can request for a RPT (a final token holding authorization data) by sending the ticket back to the authorization server.
+
+For more details, take a look at link:../service/authorization/authorization-api.html[Authorization API] and https://docs.kantarainitiative.org/uma/rec-uma-core.html[UMA] specification.

topics/permission/create-resource.adoc

@@ -17,7 +17,8 @@ can identify them more easily and also know what they actually mean
 * *Description*
 +
 A string with more details about this policy
-+
+
+[[_apply_resource_type]]
 * *Apply To Resource Type*
 +
 Specifies if this permission would be applied to all resources with a given type. When you select this field, you'll be prompted to enter the resource type to protect.

topics/permission/create-scope.adoc

@@ -1,4 +1,4 @@
-== Creating Resource-based Permissions
+== Creating Scope-based Permissions
 
 A Scope-based permission defines a set of one or more scopes to protect using a set of one or more authorization policies. Unlike the resource-based permissions, this permission type
 allows you to create permissions not only for a resource, but also for the scopes associated with it, providing more granularity when defining the permissions that govern your resources and the

topics/permission/typed-resource-permission.adoc

@@ -0,0 +1,18 @@
+== Typed Resource Permission
+
+Resource permissions can also be used to define policies that must be applied to all resources with a given link:../resource/create.adoc#_type[Type]. This form of resource-based permission can be very handy when you have resources sharing very common access requirements and constraints.
+
+Usually, resources within an application can be categorized (or typed) based on the data they encapsulate or the functionality they provide. For instance, a financial application manages different
+banking accounts where each one belongs to a specific customer. Although they are different banking account, they usually share some very common security requirements and constraints, where those are globaly
+defined by the banking organization. With typed resource permissions you may want to define some very common policies to all banking accounts:
+
+* Only the owner can manage his account
+* Only allow access from the owner's country and/or region
+* Enforce a specific authentication method
+* And so forth ...
+
+To create a typed resource permission, just click on link:./create-resource.adoc#_apply_resource_type[Apply to Resource Type] when creating a new resource permissions. Once you do that,
+you should be able to specify the type that you want to protect as well the policies that must be applied in order to govern access to all resources with type you have provided.
+
+.Example of a Typed Resource Permission
+image:../../images/typed-resource-perm-example.png[alt="Example of a Typed Resource Permission"]

topics/policy/js-policy.adoc

@@ -65,4 +65,4 @@ if (identity.hasRole('admin') || email.endsWith('@keycloak.org')) {
 ```
 
 When writing your own rules, keep in mind that the *$evaluation* object is just a object implementing *org.keycloak.authorization.policy.evaluation.Evaluation*. For more details about what you can access from this interface,
-please take a look at link::/policy/evaluation-api.adoc[Evaluation API].
+please take a look at link:evaluation-api.adoc[Evaluation API].

topics/resource-server/default-config.adoc

@@ -18,30 +18,19 @@ wildcard pattern that tells {{book.project.name}} that this resource represents
 when enabling link:../enforcer/overview.html[Policy Enforcement] to your application, all the permissions associated with the resource
 will be checked before granting access.
 
+The `Type` aforementioned defines a value that can be used to create link:../permission/typed-resource-permission.adoc[Typed Resource Permissions] that must be applied
+to the default resource or any other resource you create using the same type.
+
 The default policy is called *Only From Realm Policy* and you can see it if you click on the `Policies` tab.
 
 .Default Policy
 image:../../images/resource-server/default-policy.png[alt="Default Policy"]
 
-This policy is a link:../policy/js-policy.html[JavaScript-Based Policy] defining a condition where only users from the same _realm_ as the
+This policy is a link:../policy/js-policy.html[JavaScript-Based Policy] defining a condition that always grant access to the resources protected by this policy. If you click on this policy you'll see that it defines a rule as follows:
-resource server are granted with access. If you click on this policy you'll see that it defines a rule as follows:
 
 ```js
-var context = $evaluation.getContext();
+// by default, grants any permission associated with this policy
-
+$evaluation.grant();
-// using attributes from the evaluation context to obtain the realm
-var contextAttributes = context.getAttributes();
-var realmName = contextAttributes.getValue('kc.realm.name').asString(0);
-
-// using attributes from the identity to obtain the issuer
-var identity = context.getIdentity();
-var identityAttributes = identity.getAttributes();
-var issuer = identityAttributes.getValue('iss').asString(0);
-
-// only users from the realm have access granted
-if (issuer.endsWith(realmName)) {
-    $evaluation.grant();
-}
 ```
 
 For last, the default permission is called *Default Permission* and you can see it if you click on the `Permissions` tab.

topics/resource/create.adoc

@@ -13,7 +13,8 @@ In {{book.project.name}}, a resource defines a small set of information that is
 * *Name*
 +
 A human-readable and unique string describing a set of one or more resources.
-+
+
+[[_type]]
 * *Type*
 +
 A string uniquely identifying the type of a set of one or more resources. Usually, the type is a URN that can be used to
@@ -40,7 +41,7 @@ However, resources can also be associated with your users, so you can create per
 
 === Managing Resources Remotely
 
-Resource management is also exposed through the link:../service/protection-api.html[Protection API] to allow resource servers to remotely manage their resources.
+Resource management is also exposed through the link:../service/protection/protection-api.html[Protection API] to allow resource servers to remotely manage their resources.
 
 When using the Protection API, resource servers can be implemented to manage resources owned by their users. In this case, you can
 specify the user identifier to configure a resource as belonging to a specific user.

topics/service/authorization/authorization-api-aapi.adoc

@@ -10,8 +10,8 @@ http://${host}:${port}/auth/realms/${realm_name}/authz/authorize
 
 When asking for a RPT, you need to provide two main things:
 
-* A permission ticket with the resources you want to access
+* A link:../protection/permission-api-papi.adoc[Permission Ticket] with the resources you want to access
-* The AAT (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
+* The link:./whatis-obtain-aat.adoc[AAT] (as a bearer token) representing user's identity and his consent to access authorization data on his behalf.
 
 ```bash
 curl -X POST

topics/service/protection/permission-api-papi.adoc

@@ -6,7 +6,7 @@ Resources servers using the UMA protocol can use a specific endpoint to manage p
 http://${host}:${port}/auth/realms/${realm_name}/authz/protection/permission
 ```
 
-A Permission ticket is a special security token type representing a permission request.  Accordingly with UMA specification, a permission ticket is:
+A link:../../overview/terminology.adoc#_permission_ticket[Permission Ticket] is a special security token type representing a permission request.  Accordingly with UMA specification, a permission ticket is:
 
 `A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client back to an authorization server, to enable the authorization server to assess the correct policies to apply to a request for authorization data.`
 

topics/service/protection/protection-api.adoc

@@ -4,7 +4,7 @@ The Protection API provides a UMA-compliant set of endpoints providing:
 
 * *Resource Registration*
 +
-From this endpoint resource servers can manage their resources remotely and enable link::/enforcer/overview.adoc[Policy Enforcers] to query the server for the resources that need protection.
+From this endpoint resource servers can manage their resources remotely and enable link::../../../../enforcer/overview.adoc[Policy Enforcers] to query the server for the resources that need protection.
 
 * *Permission Registation*
 +

topics/service/protection/token-introspection.adoc

@@ -6,7 +6,7 @@ to enforce authorization decisions at the resource server side.
 There are two main use cases where token introspection may help you:
 
 * When clients applications need to check the token validity in order to obtain a new one with the same or even additional permissions
-* When enforcing authorization decisions at the resource server side, specially when none of the built-in link:../enforcer/overview.html[Policy Enforcers] fits to your application
+* When enforcing authorization decisions at the resource server side, specially when none of the built-in link:../../enforcer/overview.html[Policy Enforcers] fits to your application
 
 === Obtaining information about a RPT
 
@@ -74,7 +74,7 @@ Not really. Both link:../../service/authorization/authorization-api.html[Authori
 In case you want to validate these tokens without a remote call to the introspection endpoint you can decode the RPT and check for its validity locally. Once you decode the token,
 you can also use the permissions within the token to enforce authorization decisions.
 
-This is pretty much what the link:../enforcer/overview.html[Policy enforcers] do, just make sure to:
+This is pretty much what the link:../../enforcer/overview.html[Policy Enforcers] do, just make sure to:
 
 * Validate RPT's signature (based on realm's public key)
 * Check for token validity based on its _exp_, _iat_ and _aud_ claims