3 Keycloak authorization strategies to secure app access

Using RBAC

Probably one of the most-used access control mechanisms, RBAC allows you to protect resources depending on whether the user is granted a role. As you learned in previous chapters, Keycloak has built-in support for managing roles, as well as for propagating those roles to your applications using tokens.

Roles usually represent a role a user has in either your organization or in the context of your application. As an example, users can be granted an administrator role to indicate they act as someone allowed to access and perform actions on any resource in your application. Or, they can be granted a people-manager role to indicate that they act as someone allowed to access and perform actions on resources related to their subordinates.

As you learned from previous chapters, Keycloak has two categories of roles: realm and client roles. Roles defined at the realm level are called realm roles. These roles usually represent the user's role within an organization, regardless of the different clients that co-exist in a realm.

On the other hand, client roles are specific to a client, and their meaning depends on the semantics used by the client.

The decision of when to define a role as a realm or client role depends on the scope the role has. If it spans multiple clients in a realm while keeping the same meaning, then a realm role makes sense. Otherwise, if only a specific client is supposed to interpret the role, having it as a client role makes more sense.

When using roles, you should also avoid role explosion. In other words, too many roles in your system make things hard to manage. One way to avoid this is to create roles very carefully, having in mind the scope they are related to (realm- or client-wide) and the granularity of the permissions associated with them in your applications. The more fine-grained the scope of a role is, the more roles you will have in your system. As a rule of thumb, do not use roles for fine-grained authorization in your system. They are just not meant for that.

In Keycloak, you can grant roles to groups. That is a powerful capability where members of a group are automatically granted roles for the group they belong to. By leveraging this capability, you should be able to overcome some of the role management issues by avoiding granting privileges individually to many users.

Keycloak also provides the concept of composite roles, a special type of role that chains other roles, where a user granted a composite role is automatically granted any role in this chain (a regular role or even another composite role). Although it is a powerful and unique feature that Keycloak has, you should use it carefully to avoid performance issues -- such as when chaining multiple composite roles -- as well as manageability issues due to the proliferation of roles in your system and the granularity of the permissions associated with them. As a recommendation, if you need to grant multiple roles to your users, you should consider using groups and assigning roles to these groups. This is a more natural permission model than using composite roles.

The way you model your system roles also has an impact on the size of tokens issued by Keycloak. Ideally, tokens should contain the minimum set of roles the client needs to authorize their users either locally or when accessing another service that consumes these tokens.

Keep in mind that the more roles your system has, the more complex it will become to maintain and manage.

In this topic, you learned about the main concepts when using RBAC in Keycloak. You also learned about some recommendations and considerations when using roles that may impact your applications in terms of maintainability and performance.

In the next topic, we will look at how Keycloak helps you to implement GBAC and recommendations when using it in applications.

Using GBAC

Keycloak allows you to manage groups for your realms. Users are put into groups to represent their relationship with a specific business unit in your organization (mapping your organization tree) or just grouped together according to their role in your applications, such as when you want to have a specific group for users that can perform administrative operations.

Usually, groups and roles are used interchangeably, and this causes some confusion when defining a permission model. In Keycloak, there is a clear separation between these two concepts where, different from roles, groups are meant to organize your users and grant permissions according to the roles associated with a group.

By allowing assigning roles to groups, Keycloak makes it a lot easier to manage roles for multiple users without forcing you to grant and revoke roles for each individual user in your realm.

Groups in Keycloak are hierarchical, and when tokens are issued, you can traverse the hierarchy by looking at the path of the group. For instance, suppose you have a human resource group. As a child of this group, you have a manager group. When Keycloak includes information about groups in tokens, you should expect this information in the following format: /human resource/manager. This information should be available for every token issued by the server where the subject (the user) is a member of the group.

Different from roles, group information is not automatically included in tokens. For that, you should associate a specific protocol mapper with your client (or a client scope with the same mapper).

In the next sections, you will learn how to include group information about users into tokens.

Mapping group membership into tokens

Different from roles, there is no default protocol mapper that automatically includes group in- formation in tokens. To do that, we need to create a protocol mapper for your client.

Alternatively, you can also create a client scope and assign it to any client in your realm. Let's start by creating the myclient client:

• Client ID: myclient

Now, create a user in Keycloak:

• Username: alice

Navigate to the myclient settings and click on the Client scopes tab. In this tab, you will see a list of all the client scopes configured for the client. Click on the myclient-dedicated link to create a add a new mapper to the client.

To create a new mapper, click on the Configure a new mapper button and select the Group Membership mapper from the list. Now, configure it as follows:

On this page, create a new mapper with the following information:

• Name: groups
• Mapper Type: Group Membership
• Token Claim Name: groups

Now, click on the Save button to create the mapper.

Let's now create a group for this user. For that, click on the Groups link in the left-hand menu:

To create a new group, click on the Create group button:

Let's create a group named Project Management Office. Type this name in the Name field and then click on the Create button.

Now, let's add the alice user as a member of this group. For that, navigate to the alice user details page and click on the Groups tab:

From this page, click on the Join Group button to associate the user as a member of the group. On this page, select the Project Management Office group and click on the Join button.

The alice user is now a member of Project Management Office.

Let's now go back to the myclient details page and use the evaluation tool to see how group information will be added to tokens.

Click on the Client Scopes tab. In this tab, click on the Evaluate sub-tab:

Search for the alice user in the User field and then click on the Generated access token link at the bottom left of the page to see if the generated token includes information about the groups that the user belongs to:

As you can see, the generated token now includes a groups claim with a list of groups the user is a member of. In this case, the user alice is a member of a single Project Management Office group.

In this section, you learned how to manage groups and how to make a user a member of a group. You also learned how to use a protocol mapper to include group information in tokens so that your application can use this information to enforce access control using the groups that a user belongs to.

In the next section, we are going to look at how your applications can use custom claims to enforce access to their resources.

Using OAuth2 scopes

At its core, Keycloak is an OAuth2 authorization server. In pure OAuth2, there are two main types of applications: clients and resource servers.

As you learned from previous chapters about OAuth2, access tokens are issued to clients so that they can act on behalf of a user, where these tokens are limited to a set of scopes based on the user's consent.

On the other hand, resource servers are the consumers of access tokens, which they need to introspect to decide whether the client can access a protected resource on the resource server accordingly to the scopes granted by the user.

As you can see, authorization using OAuth2 scopes is solely based on user consent. It is the best strategy when you want third parties integrating with your APIs so that you delegate to your users the decision on whether a third-party application can access their resources. In this strategy, the main point is to protect user information rather than regular resources at the resource server. There is a fundamental difference between using OAuth2 scopes and the other authorization strategies you learned so far, mainly in terms of the entity you are protecting your system from. By using OAuth2 scopes, you are protecting your system from clients, whereas when using RBAC, for instance, you are protecting your system from users. In a nutshell, you are basically checking whether a client is allowed to perform some action or access a resource on behalf of the user, the usual delegation use case solved by OAuth2.

By default, clients in Keycloak are configured to not ask for user consent. The reason for that is that Keycloak is usually used in enterprise use cases. In contrast with the delegation use case, there is no need for user consent because clients are within the enterprise boundaries and the resources they need to access do not depend on any consent from users but on the permissions granted to them by a system administrator. Here, clients are more interested in authenticating users, where the scope of access is defined according to the roles, groups, or even specific attributes associated with a user.

Kyle Johnson is technology editor for TechTarget Security.

Stian Thorgersen started out at Arjuna Technologies building a cloud federation platform before eventually joining Red Hat as senior principal software engineer. He focuses on identity and access management for both Red Hat and its customers.

Pedro Igor Silva began his career in 2000 at an ISP, where he worked on open source projects, such as FreeBSD and Linux. He is now principal software engineer at Red Hat and is one of the core developers of Keycloak.