Chapter 9. Roles
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.
9.1. 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 the Roles left menu item.
To create a role, click Add Role on this page, enter in the name and description of the role, and click Save.
Add Role
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 Server Developer Guide for more information on localization. If a client requires user consent, this description string is displayed on the consent page for the user.
If the client has to explicitly request for a realm role, set Scope Param Required to true. The role then has to be specified using the scope parameter when requesting a token. Multiple realm roles are separated by space:
scope=admin user
9.2. Client Roles
Client roles are basically a namespace dedicated to a client. 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.
If the client has to explicitly request another client’s role, the role has to prefixed with the client ID when performing a request using the scope parameter. For example, if the client ID is account and the role is admin, the scope parameter is:
`scope=account/admin`
As noted in the realm roles section, multiple roles are separated by spaces.
9.3. 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
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.
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.
9.4. User Role Mappings
User role mappings can be assigned individually to each user through the Role Mappings tab for that single user.
Role Mappings
In the above example, we are about to assign the composite role developer that was created in the Composite Roles chapter.
Effective Role Mappings
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.
9.4.1. Default Roles
Default roles allow you to automatically assign user role mappings when any user is newly created or imported through Identity Brokering. To specify default roles go to the Roles left menu item, and click the Default Roles tab.
Default Roles
As you can see from the screenshot, there are already a number of default roles set up by default.
9.5. 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 Red Hat Single Sign-On, 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
You can see from the picture that the effective 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 client templates to define the scope for a whole set of clients.
Partial Scope
