From e880b7769247f617c62c2f472a0ddac53a2062c6 Mon Sep 17 00:00:00 2001 From: Bill Burke Date: Wed, 28 May 2014 09:31:33 -0400 Subject: [PATCH] update docs --- core/src/main/java/org/keycloak/Config.java | 2 +- docbook/reference/en/en-US/master.xml | 2 + .../reference/en/en-US/modules/Overview.xml | 33 +++++++++-- .../en/en-US/modules/admin-permissions.xml | 21 ++++--- .../modules/per-realm-admin-permissions.xml | 59 +++++++++++++++++++ .../en/en-US/modules/server-installation.xml | 8 +-- .../main/webapp/WEB-INF/keycloak-server.json | 2 +- .../resources/META-INF/keycloak-server.json | 2 +- .../resources/META-INF/keycloak-server.json | 2 +- 9 files changed, 112 insertions(+), 19 deletions(-) create mode 100755 docbook/reference/en/en-US/modules/per-realm-admin-permissions.xml mode change 100644 => 100755 project-integrations/aerogear-ups/auth-server/src/main/webapp/WEB-INF/keycloak-server.json mode change 100644 => 100755 server/src/main/resources/META-INF/keycloak-server.json mode change 100644 => 100755 testsuite/integration/src/main/resources/META-INF/keycloak-server.json diff --git a/core/src/main/java/org/keycloak/Config.java b/core/src/main/java/org/keycloak/Config.java index 46c6fc9819..16a320cd77 100755 --- a/core/src/main/java/org/keycloak/Config.java +++ b/core/src/main/java/org/keycloak/Config.java @@ -12,7 +12,7 @@ public class Config { } public static String getAdminRealm() { - return configProvider.scope("admin").get("realm", "keycloak-admin"); + return configProvider.scope("admin").get("realm", "master"); } public static String getProvider(String spi) { diff --git a/docbook/reference/en/en-US/master.xml b/docbook/reference/en/en-US/master.xml index e3b165925e..f8d3626682 100755 --- a/docbook/reference/en/en-US/master.xml +++ b/docbook/reference/en/en-US/master.xml @@ -6,6 +6,7 @@ + @@ -60,6 +61,7 @@ This one is short &Installation; &OpenShift; &AdminPermissions; + &PerRealmAdminPermissions; Adapters diff --git a/docbook/reference/en/en-US/modules/Overview.xml b/docbook/reference/en/en-US/modules/Overview.xml index ec483067af..a6ca411123 100755 --- a/docbook/reference/en/en-US/modules/Overview.xml +++ b/docbook/reference/en/en-US/modules/Overview.xml @@ -23,6 +23,10 @@ Social Login. Enable Google, GitHub, Facebook, Twitter social login with no code required. + + LDAP and Active Directory support. + + Optional User Registration @@ -32,7 +36,25 @@ - Pluggable theme and style support for user facing screens. + Forgot password support. User can have an email sent to them + + + + Reset password/totp. Admin can force a password reset, or set up a temporary password. + + + + Not-before revocation policies per realm, application, or user. + + + + User session management. Admin can view user sessions and what applications/clients have an access token. Sessions can be invalidated + per realm or per user. + + + + Pluggable theme and style support for user facing screens. Login, grant pages, account mgmt, and admin console all + can be styled, branded, and tailored to your application and organizational needs. @@ -64,11 +86,14 @@ Admin Console for managing users, roles, role mappings, applications, user sessions, allowed CORS web origins, and OAuth clients. - Account Management console that allows users to manage their own account + Account Management console that allows users to manage their own account, view their open sessions, reset passwords, etc. Deployable as a WAR, appliance, or on Openshift. + + Multitenancy support. You can host and manage multiple realms for multiple organizations. + Supports JBoss AS7, EAP 6.x, Wildfly and JavaScript applications. Plans to support Node.js, RAILS, GRAILS, and other non-Java deployments @@ -100,7 +125,7 @@
How Does Security Work in Keycloak? - Keycloak uses access tokens. Access tokens contains security metadata specifying the + Keycloak uses access tokens to secure web invocations. Access tokens contains security metadata specifying the identity of the user as well as the role mappings for that user. The format of these tokens is a Keycloak extension to the JSON Web Token specification. Each realm has a private and public key pair which it uses to digitally sign the access token using the JSON Web Signature specification. @@ -114,7 +139,7 @@ no need for them to store any security metadata locally other than the public key of the realm. - Signed access tokens can also be proprogated by REST client requests within an Authorization + Signed access tokens can also be propagated by REST client requests within an Authorization header. This is great for distributed integration as applications can request a login from a client to obtain an access token, then invoke any aggregated REST invocations to other services using that access token. So, you have a distributed security model that is centrally managed, yet does not require a Keycloak Server hit diff --git a/docbook/reference/en/en-US/modules/admin-permissions.xml b/docbook/reference/en/en-US/modules/admin-permissions.xml index a55f734f5e..00bbfc1669 100755 --- a/docbook/reference/en/en-US/modules/admin-permissions.xml +++ b/docbook/reference/en/en-US/modules/admin-permissions.xml @@ -1,13 +1,20 @@ - Admin Access Control + Master Admin Access Control - Access to The Admin Console and REST endpoints can be controlled by mapping roles to users in the keycloak-admin realm. + 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 keycloak-admin realm. These are: + There are two realm roles in the master realm. These are: admin - This is the super-user role and grants permissions to all operations on all realms @@ -18,7 +25,7 @@ - To add these roles to a user select the keycloak-admin realm, then click on Users. + 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. @@ -27,7 +34,7 @@
Realm Specific Roles - Each realm in Keycloak is represented by an application in the keycloak-admin realm. The name of the application + 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: @@ -60,10 +67,10 @@ 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 keycloak-admin realm, then click on Users. + 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.
- \ No newline at end of file + diff --git a/docbook/reference/en/en-US/modules/per-realm-admin-permissions.xml b/docbook/reference/en/en-US/modules/per-realm-admin-permissions.xml new file mode 100755 index 0000000000..a8469691fd --- /dev/null +++ b/docbook/reference/en/en-US/modules/per-realm-admin-permissions.xml @@ -0,0 +1,59 @@ + + Per Realm Admin Access Control + + Administering your realm through the master realm as discussed in 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 privleges 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. + + + realm-admin - This is a composite role that grants all admin privileges for managing + security for that realm. + + + These are more fine-grain roles you can assign to the user. + + + + view-realm - View the realm configuration + + + view-users - View users (including details for specific user) in the realm + + + view-applications - View applications in the realm + + + view-clients - View clients in the realm + + + + manage-realm - Modify the realm configuration (and delete the realm) + + + manage-users - Create, modify and delete users in the realm + + + manage-applications - Create, modify and delete applications in the realm + + + manage-clients - Create, modify and delete clients in the realm + + + 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. + +
+ diff --git a/docbook/reference/en/en-US/modules/server-installation.xml b/docbook/reference/en/en-US/modules/server-installation.xml index 70f14f4f23..0627543ae0 100755 --- a/docbook/reference/en/en-US/modules/server-installation.xml +++ b/docbook/reference/en/en-US/modules/server-installation.xml @@ -54,8 +54,8 @@ keycloak-appliance-dist-all-1.0-beta-1-SNAPSHOT/ standalone.bat script is used to start the server. After executing that, log into the admin console at - http://localhost:8080/auth/rest/admin/login. + url="http://localhost:8080/auth/admin/index.html"> + http://localhost:8080/auth/admin/index.html. Username: admin Password: admin. Keycloak will then prompt you to enter in a new password. @@ -102,8 +102,8 @@ keycloak-war-dist-all-1.0-beta-1-SNAPSHOT/ After booting up the JBoss or Wildfly distro, you can then make sure it is installed properly by logging into the admin console at - http://localhost:8080/auth/rest/admin/login. + url="http://localhost:8080/auth/admin/index.html"> + http://localhost:8080/auth/admin/index.html. Username: admin Password: admin. Keycloak will then prompt you to enter in a new password. diff --git a/project-integrations/aerogear-ups/auth-server/src/main/webapp/WEB-INF/keycloak-server.json b/project-integrations/aerogear-ups/auth-server/src/main/webapp/WEB-INF/keycloak-server.json old mode 100644 new mode 100755 index 3e88c8a134..33b4c94817 --- a/project-integrations/aerogear-ups/auth-server/src/main/webapp/WEB-INF/keycloak-server.json +++ b/project-integrations/aerogear-ups/auth-server/src/main/webapp/WEB-INF/keycloak-server.json @@ -1,6 +1,6 @@ { "admin": { - "realm": "keycloak-admin" + "realm": "master" }, "model": { diff --git a/server/src/main/resources/META-INF/keycloak-server.json b/server/src/main/resources/META-INF/keycloak-server.json old mode 100644 new mode 100755 index 06efa79534..af4c79e2cf --- a/server/src/main/resources/META-INF/keycloak-server.json +++ b/server/src/main/resources/META-INF/keycloak-server.json @@ -1,6 +1,6 @@ { "admin": { - "realm": "keycloak-admin" + "realm": "master" }, "audit": { diff --git a/testsuite/integration/src/main/resources/META-INF/keycloak-server.json b/testsuite/integration/src/main/resources/META-INF/keycloak-server.json old mode 100644 new mode 100755 index 251dfa48b4..13b70f8878 --- a/testsuite/integration/src/main/resources/META-INF/keycloak-server.json +++ b/testsuite/integration/src/main/resources/META-INF/keycloak-server.json @@ -1,6 +1,6 @@ { "admin": { - "realm": "keycloak-admin" + "realm": "master" }, "audit": {