diff --git a/SUMMARY.adoc b/SUMMARY.adoc index a0583da013..14df00d5ae 100755 --- a/SUMMARY.adoc +++ b/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] diff --git a/images/policy/create-role.png b/images/policy/create-role.png index f372df1d70..d918a42b39 100644 Binary files a/images/policy/create-role.png and b/images/policy/create-role.png differ diff --git a/topics/policy/role-policy-required-role.adoc b/topics/policy/role-policy-required-role.adoc new file mode 100644 index 0000000000..fdd101a2a1 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/topics/policy/role-policy.adoc b/topics/policy/role-policy.adoc index d3ee7015de..183fe265fe 100644 --- a/topics/policy/role-policy.adoc +++ b/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* +