<!--
~ Copyright 2016 Red Hat, Inc. and/or its affiliates
~ and other contributors as indicated by the @author tags.
~
~ Licensed under the Apache License, Version 2.0 (the "License");
~ you may not use this file except in compliance with the License.
~ You may obtain a copy of the License at
~
~ http://www.apache.org/licenses/LICENSE-2.0
~
~ Unless required by applicable law or agreed to in writing, software
~ distributed under the License is distributed on an "AS IS" BASIS,
~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~ See the License for the specific language governing permissions and
~ limitations under the License.
-->
<chapter id="roles">
<title>Roles</title>
<para>
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.
</para>
<para>
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.
</para>
<section>
<title>Composite Roles</title>
<para>
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.
</para>
<para>
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.
</para>
</section>
</chapter>