Merge pull request #204 from pedroigor/master

Group policy docs and minor fixes to summary

authorization_services/topics.adoc

@@ -51,6 +51,10 @@ include::topics/policy/aggregated-policy.adoc[]
 
 include::topics/policy/client-policy.adoc[]
 
+include::topics/policy/group-policy.adoc[]
+
+include::topics/policy/group-policy-extend-children.adoc[]
+
 include::topics/policy/logic.adoc[]
 
 include::topics/policy/evaluation-api.adoc[]

authorization_services/topics/policy/group-policy-extend-children.adoc

@@ -0,0 +1,12 @@
+[[_policy_group_extend_access_children]]
+==== Extending Access to Child Groups
+
+By default, when you add a group to this policy, access restrictions will only apply to members of the selected group.
+
+Under some circumstances, it might be necessary to allow access not only to the group itself but to any child group in the hierarchy. For any group
+added you can mark a checkbox *Extend to Children* in order to extend access to child groups.
+
+.Extending Access to Child Groups
+image:{project_images}/policy/create-group-extend-children.png[alt="Extending Access to Child Groups"]
+
+In the example above, the policy is granting access for any user member of *IT* or any of its children.

authorization_services/topics/policy/group-policy.adoc

@@ -0,0 +1,35 @@
+[[_policy_group]]
+=== Group-Based Policy
+
+You can use this type of policy to define conditions for your permissions where a set of one or more groups (and their hierarchies) is permitted to access an object.
+
+To create a new group-based policy, select *Group* in the dropdown list in the upper right corner of the policy listing.
+
+.Add Group-Based Policy
+image:{project_images}/policy/create-group.png[alt="Add Group-Based Policy"]
+
+==== Configuration
+
+* *Name*
++
+A human-readable and unique string describing 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.
++
+* *Groups Claim*
++
+Specifies the name of the claim in the token holding the group names and/or paths. Usually, authorization requests are processed based on an ID Token or Access Token
+previously issued to a client acting on behalf of some user. The token must include a claim from where this policy is going to obtain the groups
+the user is a member.
++
+* *Groups*
++
+Allows you to select the groups that should be enforced by this policy when evaluating permissions. After adding a group, you can extend access to children of the group
+by marking the checkbox *Extend to Children*. If left unmarked, access restrictions only applies to the selected group.
++
+* *Logic*
++
+The <<_policy_logic, Logic>> of this policy to apply after the other conditions have been evaluated.

authorization_services/topics/policy/role-policy-required-role.adoc

@@ -1,5 +1,5 @@
 [[_policy_rbac_required]]
-=== Defining a Role as Required
+==== Defining a Role as Required
 
 When creating a role-based policy, you can specify a specific role as `Required`. When you do that, the policy will grant access
 only if the user requesting access has been granted *all* the *required* roles. Both realm and client roles can be configured as such.

authorization_services/topics/resource-server/default-config.adoc

@@ -45,5 +45,8 @@ This permission is a <<_permission_create_resource, resource-based permission>>,
 
 You can change the default configuration by removing the default resource, policy, or permission definitions and creating your own.
 
+The default resource is created with an **URI** that maps to any resource or path in your application using a **/*** pattern. Before creating your own resources, permissions and policies, make
+sure the default configuration doesn't conflict with your own settings.
+
 [NOTE]
 The default configuration defines a resource that maps to all paths in your application. If you are about to write permissions to your own resources, be sure to remove the *Default Resource* or change its ```URI``` field to a more specific path in your application. Otherwise, the policy associated with the default resource (which by default always grants access) will allow {project_name} to grant access to any protected resource.

authorization_services/topics/service/rpt/overview.adoc

@@ -1,5 +1,5 @@
 [[_service_rpt_overview]]
-==== Requesting Party Token
+=== Requesting Party Token
 
 A requesting party token (RPT) is a https://tools.ietf.org/html/rfc7519[JSON web token (JWT)] digitally signed using https://www.rfc-editor.org/rfc/rfc7515.txt[JSON web signature (JWS)]. The token is built based on the OAuth2 access token previously issued by {project_name} to a specific client acting on behalf of an user
 or on its own behalf.

authorization_services/topics/service/rpt/token-introspection.adoc

@@ -1,5 +1,5 @@
 [[_service_protection_token_introspection]]
-=== Introspecting a Requesting Party Token
+==== Introspecting a Requesting Party Token
 
 Sometimes you might want to introspect a requesting party token (RPT) to check its validity or obtain the permissions within the token to enforce authorization decisions on the resource server side.