roles

SUMMARY.adoc

@@ -45,10 +45,16 @@
  .. link:topics/clients/client-registration.adoc[Client Registration]
  .. link:topics/clients/protocol-mappers.adoc[Token and Assertion Mappings]
  .. link:topics/clients/installation.adoc[Generating Client Adapter Config]
- . link:topics/admin-permissions.adoc[Master Admin Access Control]
- . link:topics/per-realm-admin-permissions.adoc[Per Realm Admin Access Control]
- . link:topics/identity-broker.adoc[Identity Broker]
+ .. link:topics/clients/client-templates.adoc[Client Templates]
  . link:topics/roles.adoc[Roles]
+ .. link:topics/roles/realm-client-roles.adoc[Realm and Client Roles]
+ .. link:topics/roles/compsite.adoc[Composite Roles]
+ .. link:topics/roles/user-role-mappings.adoc[User Role Mappings]
+ ... link:topics/roles/default-roles[Default Roles]
+ .. link:topics/roles/client-scope.adoc[Client Scope]
+ . link:topics/admin-permissions.adoc[Master Admin Access Control]
+ . link:topics/per-realm-admin-permissions.adoc[Admin Console Access Control]
+ . link:topics/identity-broker.adoc[Identity Broker]
  . link:topics/groups.adoc[Groups]
  . link:topics/cors.adoc[CORS]
  . link:topics/timeouts.adoc[Cookie settings, Session Timeouts, and Token Lifespans]

topics/clients/client-templates.adoc

@@ -0,0 +1,18 @@
+
+=== Client Templates
+
+If you have a lot of applications you need to secure and register within your organization it can become quite tedious
+to configure the <<fake/../../clients/protocol-mappers.adoc#_protocol-mappers, protocol mappers>> and <<fake/../../roles/client-scope.adoc#_client-scope, scope>>
+for each of these clients.  {{book.project.name}} allows you to define shared client configuration in an entity called a _client template_.
+
+To create a client template, go to the `Client Templates` left menu item.  This initial screen shows you a list of currently defined templates.
+
+To create a template click the `Create` button.  This brings you to a simple screen in which you name the template and hit save.
+A _client template_ will have similar tabs to regular clients.  You'll be able to define <<fake/../../clients/protocol-mappers.adoc#_protocol-mappers, protocol mappers>>
+and <<fake/../../roles/client-scope.adoc#_client-scope, scope>> which can be inherited by other clients.
+
+Having a client inherit from a template is as simple as choosing the template from the `Client Template` drop down list on either the
+`Add Client` or client `Settings` tab.  You will see the `Mappers` and `Scope` tabs get additional switches which allow you
+to turn on or off inheriting from the parent template.
+
+Future versions of client templating may get more inheritable configuration options, but for now, that's all there is to talk about.

topics/identity-broker.adoc

@@ -1,4 +1,6 @@
-= Identity Broker
+[[_identity-brokering]]
+
+== Identity Brokering
 
 An Identity Broker is an intermediary service that connects multiple service providers with different identity providers.
 As an intermediary service, the identity broker is responsible to create a trust relationship with an external identity provider in order to use its identities to access internal services exposed by service providers. 
@@ -21,7 +23,7 @@ In the next sections we'll see how to configure and use Keycloak as an identity
 * `Identity Federation`            
 
 [[_identity_broker_overview]]
-== Overview
+=== Overview
 
 When using Keycloak as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm.
 Instead of that, they are presented with a list of identity providers from where they can pick one and authenticate.
@@ -62,7 +64,7 @@ As you may notice, at the end of the authentication process Keycloak will always
 They don't need to know which protocol (eg.: SAML, OpenID Connect, oAuth, etc) was used or how the user's identity was validated.
 They only need to know about Keycloak ! 
 
-== Configuration
+=== Configuration
 
 The identity broker configuration is all based on identity providers.
 Identity providers are created for each realm and by default they are enabled for every single application.
@@ -163,14 +165,14 @@ Regardless the identity provider you are creating, you'll see the following conf
 
 On the next sections, we'll see how to configure each type of identity provider individually. 
 
-== Social Identity Providers
+=== Social Identity Providers
 
 Forcing users to register to your realm when they want to access applications is hard.
 So is trying to remember yet another username and password combination.
 Social identity providers makes it easy for users to register on your realm and quickly sign in using a social network.
 Keycloak provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, Github, LinkedId, Microsoft and StackOverflow. 
 
-=== Google
+==== Google
 
 To enable login with Google you first have to create a project and a client in the https://cloud.google.com/console/project[Google Developer Console].
 Then you need to copy the client id and secret into the Keycloak Admin Console. 
@@ -235,7 +237,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== Facebook
+==== Facebook
 
 To enable login with Facebook you first have to create an application in the https://developers.facebook.com/[Facebook Developer Console].
 Then you need to copy the client id and secret into the Keycloak Admin Console. 
@@ -297,7 +299,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== Twitter
+==== Twitter
 
 To enable login with Twtter you first have to create an application in the https://dev.twitter.com/apps[Twitter Developer Console].
 Then you need to copy the consumer key and secret into the Keycloak Admin Console. 
@@ -342,7 +344,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== Github
+==== Github
 
 To enable login with GitHub you first have to create an application in https://github.com/settings/applications[GitHub Settings].
 Then you need to copy the client id and secret into the Keycloak Admin Console. 
@@ -392,7 +394,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== LinkedIn
+==== LinkedIn
 
 To enable login with LinkedIn you first have to create an application in https://www.linkedin.com/secure/developer[LinkedIn Developer Network].
 Then you need to copy the client id and secret into the Keycloak Admin Console. 
@@ -444,7 +446,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== Microsoft
+==== Microsoft
 
 To enable login with Microsoft account you first have to register an OAuth application on https://account.live.com/developers/applications/index[Microsoft account Developer Center].
 Then you need to copy the client id and secret into the Keycloak Admin Console. 
@@ -493,7 +495,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-=== StackOverflow
+==== StackOverflow
 
 To enable login with StackOverflow you first have to register an OAuth application on https://stackapps.com/[StackApps].
 Then you need to copy the client id, secret and key into the Keycloak Admin Console. 
@@ -536,7 +538,7 @@ The table below lists some additional configuration options you may use when con
                             
 |===
 
-== SAML v2.0 Identity Providers
+=== SAML v2.0 Identity Providers
 
 Keycloak can broker identity providers based on the SAML v2.0 protocol. 
 
@@ -607,7 +609,7 @@ You can also import all this configuration data by providing a URL or XML file t
 Once you create a SAML provider, there is an `EXPORT` button that appears when viewing that provider.
 Clicking this button will export a SAML entity descriptor which you can use to 
 
-=== SP Descriptor
+==== SP Descriptor
 
 The SAML SP Descriptor XML file for the broker is available publically by going to this URL
 
@@ -619,7 +621,7 @@ The SAML SP Descriptor XML file for the broker is available publically by going
 
 This URL is useful if you need to import this information into an IDP that needs or is more user friendly to load from a remote URL. 
 
-== OpenID Connect v1.0 Identity Providers
+=== OpenID Connect v1.0 Identity Providers
 
 Keycloak can broker identity providers based on the OpenID Connect v1.0 protocol. 
 
@@ -686,7 +688,7 @@ In this case, the brokered identity provider must support the Authorization Code
 
 You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification) 
 
-== Retrieving Tokens from Identity Providers
+=== Retrieving Tokens from Identity Providers
 
 Keycloak allows you to store tokens and responses from identity providers during the authentication process.
 For that, you can use the `Store Token` configuration option, as mentioned before. 
@@ -712,7 +714,7 @@ In the broker configuration page you can automatically assign this role to newly
 
 NOTE: If your application is not at the same origin as the authentication server, make sure you have properly configured CORS. 
 
-== Automatically Select and Identity Provider
+=== Automatically Select and Identity Provider
 
 Each Identity provider has option `Authenticate By Default`, which allows that Identity provider is automatically selected during authentication.
 User won't even see Keycloak login page, but is automatically redirected to the identity provider. 
@@ -743,7 +745,7 @@ keycloak.createLoginUrl({
 });
 ----
 
-== Mapping/Importing SAML and OIDC Metadata
+=== Mapping/Importing SAML and OIDC Metadata
 
 You can import SAML assertion data, OpenID Connect ID Token claims, and Keycloak access token claims into new users that are imported from a brokered IDP.
 After you configure a broker, you'll see a `Mappers`            button appear.
@@ -754,7 +756,7 @@ Broker mappers can import SAML attributes or OIDC ID/Access token claims into us
 You can assign a role mapping to a user if a claim or external role exists.
 There's a bunch of options here so just mouse over the tool tips to see what each mapper can do for you. 
 
-== Mapping/Importing User profile data from Social Identity Provider
+=== Mapping/Importing User profile data from Social Identity Provider
 
 You can import user profile data provided by social identity providers like Google, GitHub, LinkedIn, Microsoft, Stackoverflow and Facebook  into new Keycloak user created from given social accounts.
 After you configure a broker, you'll see a `Mappers`            button appear.
@@ -769,7 +771,7 @@ To investigate structure of user profile JSON data provided by social providers
 Then you can find user profile  JSON structure in Keycloak log file.
  
 
-== User Session Data
+=== User Session Data
 
 After a user logs in from the external IDP, there's some additional user session note data that Keycloak stores that you can access.
 This data can be propagated to the client requesting a login via the token or SAML assertion being passed back to it by using an appropriate client mapper. 
@@ -778,7 +780,7 @@ BROKER_PROVIDER_ID::
   This is the IDP alias of the broker used to perform the login.         
 
 [[_identity_broker_first_login]]
-== First Login Flow
+=== First Login Flow
 
 When Keycloak successfully authenticates user through identity provider (step 8 in <<_identity_broker_overview,Overview>> chapter), there can be two situations: 
 
@@ -800,7 +802,7 @@ See <<_auth_spi,Authentication Flows SPI>> for more details on how to do it.
 For `First Broker Login` case, it might be useful if your Authenticator is subclass of `org.keycloak.authentication.authenticators.broker.AbstractIdpAuthenticator`            so you have access to all details about authenticated Identity provider account.
 But it's not a requirement. 
 
-=== Default First Login Flow
+==== Default First Login Flow
 
 Let's describe the default behaviour provided by `First Broker Login` flow.
 There are those authenticators: 
@@ -834,7 +836,7 @@ Verify Existing Account By Re-authentication::
   User can also re-authenticate with some different identity provider, which is already linked to his keycloak account.
   You can also force users to use OTP, otherwise it's optional and used only if OTP is already set for user account.             
 
-== Examples
+=== Examples
 
 Keycloak provides some useful examples about how to use it as an identity broker.
 Take a look at `{KEYCLOAK_HOME}/examples/broker` for more details. 

topics/roles.adoc

@@ -1,22 +1,9 @@
-= Roles
+== Roles
 
-In Keycloak, roles can be defined globally at the realm level, or individually per application.
-Each role has a name which must be unique at the level it is defined in, i.e.
-you can have only one "admin" role at the realm level.
-You may have that a role named "admin" within an Application too, but "admin" must be unique for that application. 
+Roles identify a type or category of user.  `Admin`, `user`, `manager`, and `employee` are all typical roles that may exist
+in an organization.
+Applications often assign access and permissions to specific roles rather than individual users as dealing
+with users can be too fine grained and hard to manage.  For example, the Admin Console has specific roles which give permission to users
+to access parts of the Admin Console UI and perform certain actions.  There is a global namespace for roles and each client also has its own
+dedicated namespace where roles can be defined.
 
-The description of a role is displayed in the OAuth Grant page when Keycloak is processing a browser OAuth Grant request.
-Look for more features being added here in the future like internationalization and other fine grain options. 
-
-== Composite Roles
-
-Any realm or application level role can be turned into a Composite Role.
-A Composite Role is a role that has one or more additional roles associated with it.
-I guess another term for it could be Role Group.
-When a composite role is mapped to the user, the user gains the permission of that role, plus any other role the composite is associated with.
-This association is dynamic.
-So, if you add  or remove an associated role from the composite, then all users that are mapped to the composite role will automatically have those permissions added or removed.
-Composites can also be used to define Client scopes. 
-
-Composite roles can be associated with any type of role Realm or Application.
-In the admin console simple flip the composite switch in the Role detail, and you will get a screen that will allow you to associate roles with the composite. 

topics/roles/client-scope.adoc

@@ -0,0 +1,31 @@
+[[_client-scope]]
+
+=== Client Scope
+
+When an OIDC access token or SAML assertion is created, all the user role mappings of the user are, by default, added as claims
+within the token or assertion.  Applications use this information to make access decisions on the resources controlled by that
+application.  In {{book.project.name}}, access tokens are digitally signed and can actually be re-used by the application
+to invoke on other remotely secured REST services.  This means that if an application gets compromised or there is a rogue
+client registered with the realm, attackers can get access tokens that have a broad range of permissions and your whole
+network is compromised.  This is where _client scope_ becomes important.
+
+_Client scope_ is a way to limit the roles that get declared inside an access token.  When a client requests that a user
+be authenticated the access token they receive back will only contain the role mappings you've explicitly specified
+for the client's scope.  This allows you to limit the permissions each individual access token has rather than giving the
+client access to all of the user's permissions.  By default, each client gets all the role mappings of the user.
+You can view this in the `Scope` tab of each client.
+
+.Full Scope
+image:../../{{book.images}}/full-client-scope.png[]
+
+As you can see from the picture, you can see that the effect roles of the scope are every declared role in the realm.
+To change this default behavior, you must explicitly turn off the `Full Scope Allowed` switch and declare the specific roles you want in each individual
+client.  Alternatively, you can also use <<fake/../../clients/client-templates.adoc#_client-templates, client templates>>
+to define the scope for a whole set of clients.
+
+.Partial Scope
+image:../../{{book.images}}/client-scope.png[]
+
+
+
+

topics/roles/composite.adoc

@@ -0,0 +1,21 @@
+[[_composite-roles]]
+
+=== Composite Roles
+
+Any realm or client level role can be turned into a _composite role_.
+A _composite role_ is a role that has one or more additional roles associated with it.
+When a composite role is mapped to the user, the user also gains the roles associated with that composite.  This inheritance
+is recursive so any composite of composites also gets inherited.
+
+To turn a regular role into a composite role, go to the role detail page and flip the `Composite Role` switch on.
+
+.Composite Role
+image:../../{{book.images}}/composite-role.png[]
+
+Once you flip this switch the role selection UI will be displayed lower on the page and you'll be able to associate
+realm level and client level roles to the composite you are creating.  In this example, the `employee` realm-level
+role was associated with the `developer` composite role.  Any user with the `developer` role will now also inherit
+the `employee` role too.
+
+NOTE: When tokens and SAML assertions are created, any composite will also have its associated roles added to the claims and
+      assertions of the authentication response sent back to the client.

topics/roles/realm-client-roles.adoc

@@ -0,0 +1,24 @@
+
+=== Realm Roles
+
+Realm level roles are a global namespace to define your roles.  You can see the list of built-in and created roles
+by clicking on the `Roles` left menu item.
+
+image:../../{{book.images}}/roles.png[]
+
+To create a role just click on the `Add Role` button on this page, enter in the name and description of the role
+and hit the `Save` button.
+
+.Add Role
+image:../../{{book.images}}/role.png[]
+
+The value for the `description` field is localizable by specifying a substitution variable with `$\{var-name}}` strings.
+The localized value is then configured within property files in your theme.  See the link:{{book.developerguide.link}}[book.developerguide.name]
+for more information on localization.  If a client requires user _consent_, this description string will be displayed on the
+consent page for the user.
+
+=== Client Roles
+
+Client roles are basically a namespace dedicated to clients.  Each client gets its own namespace.  Client roles are managed
+under the `Roles` tab under each individual client.  You interact with this UI the same way you do for realm level roles.
+

topics/roles/user-role-mappings.adoc

@@ -0,0 +1,18 @@
+
+=== User Role Mappings
+
+User role mappings can be assigned individually to each user through the `Role Mappings` tab for that single user.
+
+.Role Mappings
+image:../../{{book.images}}/user-role-mappings.png[]
+
+In the above example, we are about to assign the composite role `developer` that was created in the <<fake/../../roles/composite.adoc#_composite-roles, Composite Roles>>
+chapter.
+
+.Effective Role Mappings
+image:../../{{book.images}}/effective-role-mappings.png[]
+
+Once the `developer` role is assigned, you see that the `employee` role that is associated with the `developer` composite shows up in the `Effective Roles`.
+`Effective Roles` are all roles that are explicitly assigned to the user as well as any roles that are inherited from composites.
+
+

topics/roles/user-role-mappings/default-roles.adoc

@@ -0,0 +1,17 @@
+
+==== Default Roles
+
+Default roles allow you to automatically assign user role mappings when any user is newly created or imported through
+<<fake/../../../user-federation.adoc#_user-federation, User Federation>> or <<fake/../../../identity-broker.adoc_identity-broker, Identity Brokering>>.
+To specify _default roles_ go to the `Roles` left menu item, and click the `Default Roles` tab.
+
+.Default Roles
+image:../../../{{book.images}}/default-roles.png[]
+
+As you can see from the screen shot, there are already a number of _default roles_ set up by default.
+
+
+
+
+
+