Merge pull request #26 from pedroigor/master

Updating role policy and adding more doc

SUMMARY.adoc

@@ -20,6 +20,7 @@
  . link:topics/policy/overview.adoc[Managing Policies]
  .. link:topics/policy/user-policy.adoc[User-Based Policy]
  .. link:topics/policy/role-policy.adoc[Role-Based Policy]
+ ... link:topics/policy/role-policy-required-role.adoc[Defining a Role as Required]
  .. link:topics/policy/js-policy.adoc[JavaScript-Based Policy]
  .. link:topics/policy/drools-policy.adoc[Drools-Based Policy]
  .. link:topics/policy/time-policy.adoc[Time-Based Policy]

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

@@ -0,0 +1,13 @@
+== Defining a Role as Required
+
+When creating a role-based policy, you may mark a specific role as `Required`. When you do that, the policy will only grant access
+if the user asking for access is granted with *all* the *required* roles. Both realm and client roles can be configured as such.
+
+.Example of Required Role
+image:../../images/policy/create-role.png[alt="Example of Required Role"]
+
+To mark a role as required, just mark the `Required` checkbox on the corresponding role you want configure as required.
+
+Required roles can be very handy when your policy defines multiple roles but only a subset of them are mandatory. In this case, you can mix realm and client roles to enable an
+even more fine-grained RBAC model to your application. For instance, you may have policies specific for a client and require a specific a client role associated with that client. Or you can just
+enforce that access is only granted based on the presence of a specific realm role. Or even have both approaches within the same policy.

topics/policy/role-policy.adoc

@@ -3,6 +3,14 @@
 This type of policy allows you to define conditions for your permissions where only a set of one or more roles is allowed
 to access an object.
 
+By default, roles added to this policy are not marked as required and the policy will grant access if the user asking for access has any of these roles. However, {{book.project.name}} also allows you
+to mark a specific role as link:role-policy-required-role.adoc[required] in case you want to enforce the presence of a role. You can even mix required and non-required roles, regardles if they are realm
+or client roles.
+
+Role policies can be very useful when you need a more restricted RBAC, where specific roles must be present in order to grant access to an object. For instance,
+you may enforce that an user must consent to letting a client application (which is acting on his behalf) access his resources. Here you can benefit from {{book.project.name}} Client Scope Mapping to
+enable consent pages or even enforce clients to explicitly provide a scope when obtaining access tokens from a {{book.project.name}} server.
+
 To create a new policy select the option *Role-Based* in the dropdown located in the right upper corner of the permission listing.
 
 .Add Role-Based Policy
@@ -19,9 +27,13 @@ can identify them more easily and also know what they actually mean
 +
 A string with more details about this policy
 +
-* *Roles*
+* *Realm Roles*
 +
-Specifies which role(s) are allowed by this policy
+Specifies which *realm* role(s) are allowed by this policy.
++
+* *Client Roles*
++
+Specifies which *client* role(s) are allowed by this policy. To enable this field you need to select a `Client` first.
 +
 * *Logic*
 +