realm admin permissions

SUMMARY.adoc

@@ -55,8 +55,9 @@
  . link:topics/groups.adoc[Groups]
  .. link:topics/groups/groups-vs-roles.adoc[Groups Vs. Roles]
  .. link:topics/groups/default-groups.adoc[Default Groups]
- . link:topics/admin-permissions.adoc[Master Admin Access Control]
- . link:topics/per-realm-admin-permissions.adoc[Admin Console Access Control]
+ . link:topics/admin-console-permissions.adoc[Admin Console Access Control and Permissions]
+ .. link:topics/admin-console-permissions/master-realm.adoc[Master Realm ]
+ .. link:topics/admin-console-permissions/per-realm.adoc[Dedicated Realm Admin Consoles]
  . link:topics/identity-broker.adoc[Identity Broker]
  . link:topics/cors.adoc[CORS]
  . link:topics/timeouts.adoc[Cookie settings, Session Timeouts, and Token Lifespans]

topics/admin-console-permissions.adoc

@@ -0,0 +1,7 @@
+[[_admin_permissions]]
+
+== Admin Console Access Control and Permissions
+
+Each realm created on the {{book.project.name}} has a dedicated Admin Console from which that realm can be managed from.
+The `master` realm is a special realm that allows admins to manage more than one realm on the system.  You can also
+define fine-grain access to users in different realms to manage the server.  This chapter goes over all the scenarios for this.

topics/admin-console-permissions/master-realm.adoc

@@ -0,0 +1,47 @@
+
+=== Master Realm Access Control
+
+The `master` realm in {{book.project.name}} is a special realm and treated differently that other realms.
+Users in the {{book.project.name}} `master` realm can be granted permission to manage zero or more realms that are deployed on the {{book.project.name}} server.
+When a realm is created, {{book.project.name}} automatically creates various roles that grant fine-grain permissions to access that new realm.
+Access to The Admin Console and Admin REST endpoints can be controlled by mapping these roles to users in the `master` realm.
+It's possible to create multiple super users,  as well as users that can only manage specific realms.
+
+==== Global Roles
+
+There are two realm-level roles in the `master` realm.
+These are: 
+
+* admin
+* create-realm        
+
+Users with the `admin` role are super users and have full access to manage any realm on the server.  Users with the `create-realm` role
+are allowed to create new realms.  Any new realm they create they will be granted full access to.
+
+==== Realm Specific Roles
+
+Admin users within the `master` realm can be granted management privileges to one or more other realms in the system.
+Each realm in {{book.project.name}} is represented by a client in the `master` realm.
+The name of the client is `<realm name>-realm`.  These clients each have client-level roles defined which define varying
+level of access to manage an individual realm.
+
+The roles available are: 
+
+* view-realm
+* view-users
+* view-applications
+* view-clients
+* view-events
+* manage-realm
+* manage-users
+* manage-applications
+* create-client
+* manage-clients
+* manage-events            
+* view-identity-providers
+* manage-identity-providers
+* impersonation
+
+Assign the roles you want to your users and they will only be able to use that specific part of the administration console
+
+

topics/admin-console-permissions/per-realm.adoc

@@ -0,0 +1,27 @@
+[[_per_realm_admin_permissions]]
+
+=== Dedicated Realm Admin Consoles
+
+Each realm has a dedicated Admin Console that can be accessed by going to the url `/auth/admin/\{realm-name}/console`.
+Users within that realm can be granted realm management permissions by assigning specific user role mappings.
+
+Each realm has a built-in client called `realm-management`.  You can view this client by going to the
+`Clients` left menu item of your realm.  This client define client-level roles that specify permissions that can be granted to manage the realm.
+
+* view-realm
+* view-users
+* view-applications
+* view-clients
+* view-events
+* manage-realm
+* manage-users
+* manage-applications
+* create-client
+* manage-clients
+* manage-events
+* view-identity-providers
+* manage-identity-providers
+* impersonation
+
+Assign the roles you want to your users and they will only be able to use that specific part of the administration console
+

topics/admin-permissions.adoc

@@ -1,47 +0,0 @@
-[[_admin_permissions]]
-
-= Master Admin Access Control
-
-You can create and manage multiple realms by logging into the `master` Keycloak admin console at `/{keycloak-root}/admin/index.html`    
-
-Users in the Keycloak `master` realm can be granted permission to manage zero or more realms that are deployed on the Keycloak server.
-When a realm is created, Keycloak automatically creates various roles that grant fine-grain permissions to access that new realm.
-Access to The Admin Console and REST endpoints can be controlled by mapping these roles to users in the `master` realm.
-It's possible to create multiple super users as well as users that have only access to certain operations in specific realms. 
-
-== Global Roles
-
-There are two realm roles in the `master` realm.
-These are: 
-
-* admin
-* create-realm        
-
-To add these roles to a user select the `master` realm, then click on `Users`.
-Find the user you want to grant permissions to, open the user and click on `Role Mappings`.
-Under `Realm Roles` assign any of the above roles to the user by selecting it and clicking on the right-arrow. 
-
-== Realm Specific Roles
-
-Each realm in Keycloak is represented by an application in the `master` realm.
-The name of the application is `<realm name>-realm`.
-This allows assigning access to users for individual realms.
-The roles available are: 
-
-* view-realm
-* view-users
-* view-applications
-* view-clients
-* view-events
-* manage-realm
-* manage-users
-* manage-applications
-* create-clients
-* manage-clients
-* manage-events            
-
-Manage roles includes permissions to view (for example a user with manage-realm role can also view the realm configuration). 
-
-To add these roles to a user select the `master` realm, then click on `Users`.
-Find the user you want to grant permissions to, open the user and click on `Role Mappings`.
-Under `Application Roles` select the application that represents the realm you're adding permissions to (`<realm name>-realm`), then assign any of the above roles to the user by selecting it and clicking on the right-arrow. 

topics/per-realm-admin-permissions.adoc

@@ -1,35 +0,0 @@
-[[_per_realm_admin_permissions]]
-
-= Per Realm Admin Access Control
-
-Administering your realm through the `master` realm as discussed in <<_admin_permissions>> may not always be ideal or feasible.
-For example, maybe you have more than one admin application that manages various admin aspects of your organization and you want to unify all these different "admin consoles" under one realm so you can do SSO between them.
-Keycloak allows you to grant realm admin privileges to users within that realm.
-These realm admins can participate in SSO for that realm and visit a keycloak admin console instance that is dedicated solely for that realm by going to the url: `/{keycloak-root}/admin/{realm}/console`    
-
-== Realm Roles
-
-Each realm has a built-in application called `realm-management`.
-This application defines roles that define permissions that can be granted to manage the realm. 
-These are more fine-grain roles you can assign to the user.
-
-* realm-admin            
-* view-realm
-* view-users
-* view-applications
-* view-clients
-* view-events
-* manage-realm
-* manage-users
-* manage-applications
-* manage-clients
-* manage-events            
-
-Manage roles includes permissions to view (for example a user with manage-realm role can also view the realm configuration). 
-
-To add these roles to a user,
-
-. Select the realm you want.
-. Then click on `Users`.
-. Find the user you want to grant permissions to, open the user and click on `Role Mappings`.
-. Under `Application Roles` select `realm-management`, then assign any of the above roles to the user by selecting it and clicking on the right-arrow.