[keycloak-dev] modeling map role fine grain permissions

[Bill Burke]

Here's how I am going to model role mapping with fine grain permissions 
in Authz service.  The goal of this is to be able to limit or expand on 
who can map specific roles.  While we want to have a default that any 
admin that has the "manage-users" role can map a role, we also want to 
be able to do things like saying that an admin can map a specific role 
if they belong to a group instead.

DEFAULT PERMISSIONS

* "permit all" policy.  Just grants it.

* "Default Role Mapping Policy" Policy.  This is an aggregate policy 
that includes the "permit all" policy.

* "map-role" scope

* "Roles" resource.  Associated scope is "map-role"

* "Default Role Mapping Permission" - scope permission that binds 
"Roles" resource and "map-role" scope.  The associated policy will be 
"Default Role Mapping Policy".


* "manage-users" scope

* "Users" resource.  Associated scope is "manage-users"

* "manage-users" policy that checks that "manage-users" role is present

* "Default Manage Users Policy".  This is an aggregate policy that 
includes the "manage-users" policy.

* "Default Manage Users Permission".  scope permission that binds 
"Users" resource and "manage-users" scope.  The associated policy will 
be "Default Manage Users Policy".


The above defines the default policy for mapping all roles.  In the 
admin console "Roles" section, there will be a "Default Admin 
Permissions" tab.  Here the user will be able to modify the "Default 
Role Mapping Permission".  The will be able to create and add new 
policies for this permission.  They will not be able to create any other 
permission.  In the "Users" section of the admin console, there will be 
a "Default Admin Permissions" tab.  Here the admin will be able to 
modify the "Default Manage Users Permission"

FINE GRAIN PERMISSION

For more fine grain permissions, there will be a resource created per 
role on demand.  The admin will go to the role's console page and there 
will be a "Admin Permissions" tab.  The admin will say they want to add 
a fine grain permission for that role and this will trigger these actions:

* A resource will be created specifically for that role with an 
associated scope of "map-role"

* A scope permission will be created for that role resource and the 
"map-role" scope.  The "Default Role Mapping Policy" will be added 
automatically to this permission.

THere will also be a "Admin Permissions" tab for each Group.  The admin 
will say they want to add a fine grain permission for that group and 
this will trigger these actions:

* A resource will be created specifically for that group with an 
associated scope of "manage-users"

* A scope permission will be created for that group resource and the 
"manage-users" scope.  The "Default Manage User Policy" will be added 
automatically to this permission.

EVALUATION

When evaluating whether or not a role is allowed to be mapped by a 
particular admin, this will be the algorithm:

1. If there is a resource for that specific role, evaluate that the 
admin can use the "map-role" scope with that role's resource

2. If there is not a resource for that specific role, then evaluate that 
teh admin can use the "map-role" scope with the "Roles" resource.

3. Evaluate if the admin can perform the "manage-users" scope on the 
"Users" resource.

4. If Step #3 fails, then for each group see if the admin has the 
"manage-users" scope for that group.

DEFAULT PERMISSIONS FOR ADMIN ROLES

By default, each admin role in the system "manage-users", 
"manage-realm", etc... will have a resource ad scope permission created 
for it as articulated above.  The scope permission will be UNANIMOUS and 
will also associate a role policy of that role in addition to the 
"Default Role Mapping Policy".  This additional role policy is basically 
saying "Admins with 'manage-users' role and the admin must have this 
role mapping as well".  So, somebody with 'manage-users' role can't map 
'manage-realm' unless they have that role themselves.

MORE FINE GRAIN PERMISSIONS

We also want to solve the case of allowing an admin to be able to map 
specific roles for members of a specific group.  To do this we'll add 
another policy type called "Has Permission".  Here you'll be able to 
link a permission to a policy.  So, to solve the use case for specific 
roles for members of a specific group, we can edit the "map-role" 
permission for a specific role and add a "Has Permission" that links to 
the permission that the admin has "manage-users" scope for a specific 
group.  Hope I'm making sense on this one.