Chapter 11. Managing access to realm resources

There are two realm-level roles in the master realm. These are:

Users with the admin role are superusers and have full access to manage any realm on the server. Users with the create-realm role are allowed to create new realms. They will be granted full access to any new realm they create.

Admin users within the master realm can be granted management privileges to one or more other realms in the system. Each realm in Red Hat build of Keycloak 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:

Assign the roles you want to your users and they will only be able to use that specific part of the administration console.

In a realm, you can manage different types of resources such as users, groups, clients, client scopes, roles, and so on. As a realm administrator, you are constantly managing these resources when managing identities and how they authenticate and are authorized to access a realm and applications.

This feature provides the necessary mechanisms to enforce access controls when managing realm resources, limited to:

You can manage permissions for all resources of a given resource type, such as all users in a realm, or for a specific realm resource, such as a specific user or set of users in the realm.

Each realm resource supports a well-defined set of management operations, or scopes, that can be performed on them, such as view, manage, and resource-specific operations such as view-members, if you take groups as an example.

When managing permissions, you are selecting a set of one or more scopes from a resource type to allow realm administrators to perform specific operations on a resource type. For instance, granting a view scope will give access to realm administrators to list, search, and view a realm resource. On the other hand, the manage scope will allow administrators to perform updates and deletes on them.

The scopes are completely independent of each other. If you give access to manage a realm resource, that does not mean the view scope is granted automatically. No transitive dependency exists between scopes. Although this might impact the overall user experience when managing permissions because you need to select individual scopes, the benefit is that you can more easily identify the permissions that enforce access to a specific scope.

Certain scopes from a resource type have a relationship (not a transitive dependency) to scopes in another resource type. This relationship is mainly true when you manage a resource type that represents a group of realm resources, such as realm groups and their members.

To enable fine-grained admin permissions in a realm, follow these steps:

Once enabled, a Permissions section appears in the left-side menu of the administration console.

From this section, you can manage the permissions for realm resources.

The Permissions tab provides an overview of all active permissions within a realm. From here, administrators can create, update, delete, or search for permissions. You can also pre-evaluate the permissions you have created to check if they are enforcing access to realm resources as expected. For more details, see Evaluating Permissions.

To create a permission, click on the Create permission button and select the resource type you want to protect.

Once you select the resource type, you can now define how access should be enforced for a set of one or more resources of the selected type:

When managing a permission you can define the following settings:

After creating the permission, it will automatically take effect when enforcing access to (all) resources and scopes you selected. Keep that fact in mind when creating and updating permissions in production.

The Policies tab allows administrators to define conditions using different access control methods to determine whether a permission should be granted to an administrator attempting to perform operations on a realm resource. When managing permissions, you must associate at least a single policy to grant or deny access to a realm resource.

Policies are basically conditions that will evaluate to either a GRANT or a DENY. Their outcome will decide whether a permission should be granted or denied.

A permission is only granted if all its associated policies evaluate to a GRANT. Otherwise, the permission is denied and a realm administrator will not be able to access the protected resource.

Red Hat build of Keycloak provides a set of built-in policies that you can choose from:

Once you have a well-defined and stable permission model for your realm, less need exists to create policies. You can instead reuse existing policies to create more permissions.

For more details about each policy type, see Managing policies.

The Evaluation tab provides a testing environment where administrators can verify that permissions are enforcing access as expected. The administrator can see what permissions are involved when enforcing access to a particular resource and what the outcome is.

You need to provide a set of fields in order to run an evaluation:

By clicking the Evaluate button, the server will evaluate all the permissions associated with the selected resource and scopes just like if the selected User were trying to access the resource when using the administration console or the Admin API.

For instance, in the example above you can see that the user myadmin can manage user user-1 because a Allow managing all realm users permission voted to a PERMIT, therefore granting access to the manage scope. However, all the other scopes were denied.

Combined with the searching capabilities from the Permissions tab, you can perform troubleshooting to identify any permission that is not behaving as expected.

When evaluating permissions, the following rules apply:

Realm administrators can access a dedicated realm-specific administration console that allows them to manage resources within their assigned realm. This console is separate from the main Red Hat build of Keycloak Admin Console, which is typically used by server administrators.

For more details on dedicated realm administration consoles and available roles, refer to: Dedicated admin consoles.

To access the administration console, a realm administrator must have at least one of the following roles assigned, depending on the resources they need to administer:

By granting any of these roles to a realm user, they will be able to access the administration console, but only for the areas that correspond to roles granted. For instance, if you assign the query-users role, the realm administrator will only have access to the Users section in the administration console. If an administrator is responsible for multiple resource types (such as both users and groups), they must have all the corresponding "query-*" roles assigned.

These roles enable basic access to query resources but do not grant permission to view or modify them. To grant or deny access to realm resources you need to set up the permissions for any of the operations available from each resource type. For more details, see Managing Permissions.

Consider a situation where an administrator wants to allow a group of administrators to manage all users in the realm except those that belong to the administrators group. This example includes a test realm and a test-admins group.

When enabling the feature to a realm, there is an additional overhead when realm administrators are managing any of the supported resource types. This is mainly true when performing these operations:

The feature introduces additional checks whenever you are listing or managing realm resources in order to enforce access based on the permissions you have defined. This is mainly true when querying realm resources due to the additional overhead to partially evaluate the permissions for a realm administrator to filter and paginate the results.

Fewer permissions referencing a realm administrator user and most of the resources they can access is better. For instance, if you want to delegate access to a realm administrator to manage users, it is better to have those users as members of a group. By doing that, you are improving not only the performance when evaluating permissions but also creating a permission model that is easier to manage.

The main impact of access enforcement is when querying realm resources. If a realm administrator is, for instance, referenced in thousands of permissions through a user, role, or group policy, the partial evaluation mechanism that happens when querying realm resources will query all those permissions from the database. A more concise and optimized model will help to fetch fewer permissions but the enough to grant or deny access to realm resources.

For instance, granting access to a realm administrator to view and manage users in a realm is better done with a group permission than create individual permissions for each individual user in a realm. As well as make sure the policies associated with a permission referencing a realm administrator either by a direct reference (user policy), or indirect (role or group policy) reference, do not span multiple (thousands of) permissions, regardless of the resource type.

As an example, suppose you have three users in a realm, and you want to allow bob, a realm administrator, to view and manage them. A non-optimal permission model would create three different permissions, for each user, where a user policy grants access to bob. Instead, you can have a single group permission, or even a single user permission, that groups those three users while still granting access to bob using the same user policy.

The same is true if you want to give access to more realm administrators to those three users. Instead of creating individual policies, you can consider using a group or role policy instead. The permission model is use-case-specific, but these recommendations are important to provide not only better manageability but also improve the overall performance of the server when managing realm resources.

In terms of server configuration, depending on the size of your realm and the number of permissions and policies you have, you might consider changing the cache configuration to increase the size of the following caches:

Consider looking at the server metrics for these caches to find the best value when sizing your deployment.

When filtering resources, the partial evaluation mechanism will eventually rely on IN clauses in SQL statements to filter the results. Depending on your database, you might have limitations on the number of parameters for the IN clause. That is the case for old versions of the Oracle database, which has a hard limit to 1000 parameters. To avoid such problems, keep in mind the considerations above about the number of permissions that grants or deny access to a single realm administrator.