diff --git a/book.json b/book.json index d0fbc6f407..601da13e9e 100755 --- a/book.json +++ b/book.json @@ -28,27 +28,31 @@ "adminguide": { "name": "Server Administration", - "link": "https://keycloak.gitbooks.io/documentation/content/server_admin/index.html" + "link": "https://keycloak.gitbooks.io/documentation/server_admin/index.html" }, "developerguide": { "name": "Server Development", - "link": "https://keycloak.gitbooks.io/documentation/content/server_development/index.html" + "link": "https://keycloak.gitbooks.io/documentation/server_development/index.html" }, "installguide": { "name": "Server Installation and Configuration", - "link": "https://keycloak.gitbooks.io/documentation/content/server_installation/index.html", + "link": "https://keycloak.gitbooks.io/documentation/server_installation/index.html" "profile": { "name": "Profiles", - "link": "https://keycloak.gitbooks.io/documentation/content/server_installation/topics/profiles.html" + "link": "https://keycloak.gitbooks.io/documentation/server_installation/topics/profiles.html" } }, "adapterguide": { "name": "Securing Applications and Services Guide", - "link": "https://keycloak.gitbooks.io/documentation/content/securing_apps/index.html" + "link": "https://keycloak.gitbooks.io/documentation/securing_apps/index.html" }, "gettingstarted": { "name": "Getting Started Tutorial", - "link": "https://keycloak.gitbooks.io/documentation/content/getting_started/index.html" + "link": "https://keycloak.gitbooks.io/documentation/getting_started/index.html" + }, + "authorizationguide": { + "name": "Authorization Services Guide", + "link": "https://keycloak.gitbooks.io/documentation/authorization_services/index.html" }, "apidocs": { "name": "API Documentation", diff --git a/server_admin/SUMMARY.adoc b/server_admin/SUMMARY.adoc index 61cc563ff2..d565a8b337 100644 --- a/server_admin/SUMMARY.adoc +++ b/server_admin/SUMMARY.adoc @@ -59,6 +59,7 @@ .. link:server_admin/topics/admin-console-permissions.adoc[Admin Console Access Control and Permissions] ... link:server_admin/topics/admin-console-permissions/master-realm.adoc[Master Realm] ... link:server_admin/topics/admin-console-permissions/per-realm.adoc[Dedicated Realm Admin Consoles] +... link:server_admin/topics/admin-console-permissions/fine-grain.adoc[Fine Grain Admin Permissions] .. link:server_admin/topics/realms/keys.adoc[Realm Keys] .. link:server_admin/topics/identity-broker.adoc[Identity Brokering] ... link:server_admin/topics/identity-broker/overview.adoc[Brokering Overview] diff --git a/server_admin/book-product.json b/server_admin/book-product.json index e103589924..a64c08955a 100644 --- a/server_admin/book-product.json +++ b/server_admin/book-product.json @@ -33,6 +33,10 @@ "name": "Securing Applications and Services Guide", "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/securing-applications-and-services-guide/" }, + "authorizationguide": { + "name": "Authorization Services Guide", + "link": "https://access.redhat.com/documentation/en/red-hat-single-sign-on/7.1/html-single/authorization_services_guide/" + }, "subsystem": { "undertow": "urn:jboss:domain:undertow:3.1" diff --git a/server_admin/keycloak-images/fine-grain-add-view-leads.png b/server_admin/keycloak-images/fine-grain-add-view-leads.png new file mode 100644 index 0000000000..ae9d683248 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-add-view-leads.png differ diff --git a/server_admin/keycloak-images/fine-grain-add-view-users.png b/server_admin/keycloak-images/fine-grain-add-view-users.png new file mode 100644 index 0000000000..5ec2ee281c Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-add-view-users.png differ diff --git a/server_admin/keycloak-images/fine-grain-assign-query-clients.png b/server_admin/keycloak-images/fine-grain-assign-query-clients.png new file mode 100644 index 0000000000..7294dd5fbb Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-assign-query-clients.png differ diff --git a/server_admin/keycloak-images/fine-grain-client-assign-user-policy.png b/server_admin/keycloak-images/fine-grain-client-assign-user-policy.png new file mode 100644 index 0000000000..ec322c8eae Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client-assign-user-policy.png differ diff --git a/server_admin/keycloak-images/fine-grain-client-manage-permissions.png b/server_admin/keycloak-images/fine-grain-client-manage-permissions.png new file mode 100644 index 0000000000..d6d0fbe1b4 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client-manage-permissions.png differ diff --git a/server_admin/keycloak-images/fine-grain-client-permissions-tab-off.png b/server_admin/keycloak-images/fine-grain-client-permissions-tab-off.png new file mode 100644 index 0000000000..abec58dd5e Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client-permissions-tab-off.png differ diff --git a/server_admin/keycloak-images/fine-grain-client-permissions-tab-on.png b/server_admin/keycloak-images/fine-grain-client-permissions-tab-on.png new file mode 100644 index 0000000000..8d8a36c2c5 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client-permissions-tab-on.png differ diff --git a/server_admin/keycloak-images/fine-grain-client-user-policy.png b/server_admin/keycloak-images/fine-grain-client-user-policy.png new file mode 100644 index 0000000000..b9247424bb Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client-user-policy.png differ diff --git a/server_admin/keycloak-images/fine-grain-client.png b/server_admin/keycloak-images/fine-grain-client.png new file mode 100644 index 0000000000..17e06403f8 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-client.png differ diff --git a/server_admin/keycloak-images/fine-grain-group-permissions-tab-on.png b/server_admin/keycloak-images/fine-grain-group-permissions-tab-on.png new file mode 100644 index 0000000000..a6a2916b9a Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-group-permissions-tab-on.png differ diff --git a/server_admin/keycloak-images/fine-grain-map-roles-permission.png b/server_admin/keycloak-images/fine-grain-map-roles-permission.png new file mode 100644 index 0000000000..636d9fcd17 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-map-roles-permission.png differ diff --git a/server_admin/keycloak-images/fine-grain-sales-admin-login.png b/server_admin/keycloak-images/fine-grain-sales-admin-login.png new file mode 100644 index 0000000000..41b2977f35 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-sales-admin-login.png differ diff --git a/server_admin/keycloak-images/fine-grain-sales-application-roles.png b/server_admin/keycloak-images/fine-grain-sales-application-roles.png new file mode 100644 index 0000000000..60a88ecc9d Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-sales-application-roles.png differ diff --git a/server_admin/keycloak-images/fine-grain-users-permissions.png b/server_admin/keycloak-images/fine-grain-users-permissions.png new file mode 100644 index 0000000000..7aaa941853 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-users-permissions.png differ diff --git a/server_admin/keycloak-images/fine-grain-view-leads-permissions.png b/server_admin/keycloak-images/fine-grain-view-leads-permissions.png new file mode 100644 index 0000000000..919774dbaa Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-view-leads-permissions.png differ diff --git a/server_admin/keycloak-images/fine-grain-view-leads-role-tab.png b/server_admin/keycloak-images/fine-grain-view-leads-role-tab.png new file mode 100644 index 0000000000..cc5878dbf7 Binary files /dev/null and b/server_admin/keycloak-images/fine-grain-view-leads-role-tab.png differ diff --git a/server_admin/topics/admin-console-permissions/fine-grain.adoc b/server_admin/topics/admin-console-permissions/fine-grain.adoc new file mode 100644 index 0000000000..1c2d05e95b --- /dev/null +++ b/server_admin/topics/admin-console-permissions/fine-grain.adoc @@ -0,0 +1,338 @@ +[[_fine_grain_permissions]] + +=== Fine Grain Admin Permissions + +Sometimes roles like `manage-realm` or `manage-users` are too coarse grain and you want to create +restricted admin accounts that have more fine grain permissions. {{book.project.name}} allows you to define +and assign restricted access policies for managing a realm. Things like: + +* Managing one specific client +* Managing users that belong to a specific group +* Managing membership of a group +* Limited user management. +* Fine grain impersonization control +* Being able to assign a specific restricted set of roles to users. +* Being able to assign a specific restricted set of roles to a composite role. +* Being able to assign a specific restricted set of roles to a client's scope. +* New general policies for viewing and managing users, groups, roles, and clients. + +There's some important things to note about fine grain admin permissions: + +* Fine grain admin permissions were implemented on top of link:{{book.authorizationguide.link}}[Authorization Services]. It is highly recommended that you read up on those features before diving into fine grain permissions. +* Fine grain permissions are only available within <> and admins defined within those realms. You cannot define cross-realm fine grain permissions. +* Fine grain permissions are used to grant additional permissions. You cannot override the + default behavior of the built in admin roles. + +==== Managing One Specific Client + +Let's look first at allowing +an admin to manage one client and one client only. In our example we have a realm +called `test` and a client called `sales-application`. In realm `test` we will give a +user in that realm permission to only manage that application. + +IMPORTANT: You cannot do cross realm fine grain permissions. Admins in the `master` realm are limited to the predefined admin roles defined in previous chapters. + +===== Permission Setup + +The first thing we must do is login to the Admin Console so we can set up permissions for that client. We navigate to the management section +of the client we want to define fine-grain permissions for. + +.Client Management +image:../../{{book.images}}/fine-grain-client.png[] + +You should see a tab menu item called `Permissions`. Click on that tab. + +.Client Permissions Tab +image:../../{{book.images}}/fine-grain-client-permissions-tab-off.png[] + +By default, each client is not enabled to do fine grain permissions. So turn the `Permissions Enabled` switch to on +to initialize permissions. + +IMPORTANT: If you turn the `Permissions Enabled` switch to off, it will delete any and all permissions you have defined for this client. + +.Client Permissions Tab +image:../../{{book.images}}/fine-grain-client-permissions-tab-on.png[] + +When you witch `Permissions Enabled` to on, it initializes various permission objects behind the scenes +using link:{{book.authorizationguide.link}}[Authorization Services]. For this example, we're +interested in the `manage` permission for the client. Clicking on that will redirect you +to the permission that handles the `manage` permission for the client. All authorization +objects are contained in the `realm-management` client's `Authorization` tab. + +.Client Manage Permission +image:../../{{book.images}}/fine-grain-client-manage-permissions.png[] + +When first initialized the `manage` permission does not have any policies associated with it. +You will need to create one by going to the policy tab. To get there fast, click on +the `Authorization` link shown in the above image. Then click on the policies tab. + +There's a pull down menu on this page called `Create policy`. There's a multitude of policies +you can define. You can define a policy that is associated with a role or a group or even define +rules in Javascript. For this simple example, we're going to create a `User Policy`. + +.User Policy +image:../../{{book.images}}/fine-grain-client-user-policy.png[] + +This policy will match a hard-coded user in the user database. In this case it is the `sales-admin` user. We must then go back to the +`sales-application` client's `manage` permission page and assign the policy to the permission object. + +.Assign User Policy +image:../../{{book.images}}/fine-grain-client-assign-user-policy.png[] + +The `sales-admin` user can now has permission to manage the `sales-application` client. + +There's one more thing we have to do. Go to the `Role Mappings` tab and assign the `query-clients` +role to the `sales-admin`. + +.Assign query-clients +image:../../{{book.images}}/fine-grain-assign-query-clients.png[] + + +Why do you have to do this? This role tells the Admin Console +what menu items to render when the `sales-admin` visits the Admin Console. The `query-clients` +role tells the Admin Console that it should render client menus for the `sales-admin` user. + +IMPORTANT If you do not set the `query-clients` role, restricted admins like `sales-admin` will not see any menu options when they log into the Admin Console + +===== Testing It Out. + +Next we log out of the master realm and and re-login to the <> for the `test` realm +using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. + +.Sales Admin Login +image:../../{{book.images}}/fine-grain-sales-admin-login.png[] + +This admin is now able to manage this one client. + +==== Restrict User Role Mapping + +Another thing you might want to do is to restrict the set a roles an admin is allowed +to assign to a user. Continuing our last example, let's expand the permission set of the 'sales-admin' +user so that he can also control which users are allowed to access this application. Through fine grain permissions we can +enable it so that the `sales-admin` can only assign roles that grant specific access to +the `sales-application`. We can also restrict it so that the admin can only map roles +and not perform any other types of user administration. + +The `sales-application` has defined three different client roles. + +.Sales Application Roles +image:../../{{book.images}}/fine-grain-sales-application-roles.png[] + +We want the `sales-admin` user to be able to map these roles to any user in the system. The +first step to do this is to allow the role to be mapped by the admin. If we click on the +`viewLeads` role, you'll see that there is a `Permissions` tab for this role. + +.View Leads Role Permission Tab +image:../../{{book.images}}/fine-grain-view-leads-role-tab.png[] + +If we click on that tab and turn the `Permissions Enabled` on, you'll see that there +are a number of actions we can apply policies to. + +.View Leads Permissions +image:../../{{book.images}}/fine-grain-view-leads-permissions.png[] + +The one we are interested in is `map-role`. Click on this permission and add the same +User Policy that was created in the earlier example. + +.Map-roles Permission +image:../../{{book.images}}/fine-grain-map-roles-permission.png[] + +What we've done is say that the `sales-admin` can map the `viewLeads` role. What we have +not done is specify which users the admin is allowed to map this role too. To do that +we must go to the `Users` section of the admin console for this realm. Clicking on the +`Users` left menu item brings us to the users interface of the realm. You should see a +`Permissions` tab. Click on that and enable it. + +.Users Permissions +image:../../{{book.images}}/fine-grain-users-permissions.png[] + +The permission we are interested in is `map-roles`. This is a restrictive policy +in that it only allows admins the ability to map roles to a user. If we click on the +`map-roles` permission and again add the User Policy we created for this, our `sales-admin` +will be able to map roles to any user. + +The last thing we have to do is add the `view-users` role to the `sales-admin`. This will +allow the admin to view users in the realm he wants to add the `sales-application` roles to. + +.Add view-users +image:../../{{book.images}}/fine-grain-add-view-users.png[] + + +===== Testing It Out. + +Next we log out of the master realm and and re-login to the <> for the `test` realm +using the `sales-admin` as a username. This is located under `/auth/admin/test/console`. + +You will see that now the `sales-admin` can view users in the system. If you select one of the +users you'll see that each user detail page is read only, except for the `Role Mappings` tab. +Going to these tab you'll find that there are no `Available` roles for the admin to +map to the user except when we browse the `sales-application` roles. + +.Add viewLeads +image:../../{{book.images}}/fine-grain-add-view-leads.png[] + +We've only specified that the `sales-admin` can map the `viewLeads` role. + +===== Per Client map-roles Shortcut + +It would be tedious if we had to do this for every client role that the `sales-application` published. +to make things easier, there's a way to specify that an admin can map any role defined +by a client. If we log back into the admin console to our master realm admin and go back + to the `sales-application` permissions page, you'll see the `map-roles` permission. + +.Client map-roles Permission +image:../../{{book.images}}/fine-grain-client-permissions-tab-on.png[] + +If you grant access to this particular parmission to an admin, that admin will be able +map any role defined by the client. + +==== Managing Users of a Specific Group + +You can specify that an admin can only manage the members of a specific group. If you go to a group's +page in the Admin Console you will see a `Permissions` tab. Clicking on that and enabling +fine grain permissions for the group will get you to something like this: + +.Group Permissions Tab +image:../../{{book.images}}/fine-grain-group-permissions-tab-on.png[] + +In this screenshot, the group we are defining permissions for is `sales`. The +`manage-members` permission allows you to define policies that allow an admin to +manage any user that is a member of the group. + +==== Full List of Permissions + +The chapter defines the whole list of permission types that can be described for +a realm. + +===== Role + +When going to the `Permissions` tab for a specific role, you will see these +permission types listed. + +map-role:: + Policies that decide if an admin can map this role to a user. These policies + only specify that the role can be mapped to a user, not that the admin is allowed + to perform user role mapping tasks. The admin will also have to have manage or + role mapping permissions. See <<_users-permissions, Users Permissions>> for more information. +map-role-composite:: + Policies that decide if an admin can map this role as a composite to another role. + An admin can define roles for a client if he has manage permissions for that client + but he will not be able to add composites to those roles unless he has the + `map-role-composite` privileges for the role he wants to add as a composite. +map-role-client-scope:: + Policies that decide if an admin can apply this role to the scope of a client. + Even if the admin can manage the client, he will not have permission to + create tokens for that client that contain this role unless this privilege + is granted. + +===== Client + +When going to the `Permissions` tab for a specific client, you will see these +permission types listed. + +view:: + Policies that decide if an admin can view the client's configuration. +manage:: + Policies that decide if an admin can view and manage the client's configuration. + There is some issues with this in that privileges could be leaked unintentionally. + For example, the admin could define a protocol mapper that hardcoded a role + even if the admin does not have privileges to map the role to the client's scope. + This is currently the limitation of protocol mappers as they don't have a way + to assign individual permissions to them like roles do. +configure:: + Reduced set of prileges to manage the client. Its like the `manage` scope except + the admin is not allowed to define protocol mappers, change the client template, + or the client's scope. +map-roles:: + Policies that decide if an admin can map any role defined by the client to a user. + This is a shortcut, easy-of-use feature to avoid having to defin policies + for each and every role defined by the client. +map-roles-composite:: + Policies that decide if an admin can map any role defined by the client + as a composite to another role. + This is a shortcut, easy-of-use feature to avoid having to define policies + for each and every role defined by the client. +map-roles-client-scope:: + Policies that decide if an admin can map any role defined by the client + to the scope of another client. + This is a shortcut, easy-of-use feature to avoid having to define policies + for each and every role defined by the client. + +[[_users-permissions]] +===== Users + +When going to the `Permissions` tab for all users, you will see these +permission types listed. + +view:: + Policies that decide if an admin can view all users in the realm. +manage:: + Policies that decide if an admin can manage all users in the realm. This + permission grants the admin the privilege to perfor user role mappings, but + it does not specify which roles the admin is allowed to map. You'll need to + define the privilege for each role you want the admin to be able to map. +map-roles:: + This is a subset of the privileges granted by the `manage` scope. In this + case the admin is only allowed to map roles. The admin is not allowed to perform + any other user management operation. Also, like `manage`, the roles that the + admin is allowed to apply must be specified per role or per set of roles if dealing + with client roles. +manage-group-membership:: + Similar to `map-roles` except that it pertains to group membership: which + groups a user can be added or removed from. These + policies just grant the admin permission to manage group membership, not which + groups the admin is allowed to manage membership for. You'll have to + specify policies for each group's `manage-members` permission. +impersonate:: + Policies that decide if the admin is allowed to impersonate other users. These + policies are applied to the admin's attributes and role mappings. +user-impersonated:: + Policies that decide which users can be impersonated. These policies will be + applied to the user being impersonated. For example, you might want to define + a policy that will forbid anybody from impersonating a user that has admin + privileges. + +===== Group + +When going to the `Permissions` tab for a specific group, you will see these +permission types listed. + +view:: + Policies that decide if the admin can view information about the group. +manage:: + Policies that decide if the admin can manage the configuration of the group. +view-members:: + Policies that decide if the admin can view the user details of members of the group. +manage-members:: + Policies that decide if the admin can manage the users that belong to this group. +manage-membership:: + Policies that decide if an admin can change the membership of the group. Add or + remove members from the group. + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/server_admin/topics/admin-console-permissions/master-realm.adoc b/server_admin/topics/admin-console-permissions/master-realm.adoc index 5bbc94077b..5a8855860c 100644 --- a/server_admin/topics/admin-console-permissions/master-realm.adoc +++ b/server_admin/topics/admin-console-permissions/master-realm.adoc @@ -42,4 +42,7 @@ The roles available are: Assign the roles you want to your users and they will only be able to use that specific part of the administration console. +IMPORTANT: Admins with the `manage-users` role will only be able to assign admin roles to users that they themselves have. So, if an admin has the `manage-users` role but doesn't have the `manage-realm` role, they will not be able to assign this role. + +