People sitting around a table

adesso Blog

Keycloak is a Java-based open-source identity and access management (IAM) solution. IAM systems allow you to manage identities and access rights for different applications and fulfil two tasks:

  • Authentication: the identity of a user is verified by providing a username and password, for instance.
  • Authorisation: after the user’s identity has been successfully verified, they are granted permissions that give them access to their resources.

I will discuss authorisation in more detail later in this post. Keycloak is a certified implementation of the OpenID Connect protocol and an established standard solution that provides a number of features out of the box. These include single sign-on, identity brokering and integration of third-party systems (such as Google or Twitter).

Basic terminology

The terms realm, client and role form the basis of how everything works in Keycloak. Each realm manages a set of users and usually contains several clients. These can be used by an application or a backend service to authenticate the users of the realm. In our example, I have created a realm with the name ‘Meine-anwendung’ (my-application) and the clients ‘meine-anwendung-webapp’ (my-application-webapp) and ‘meine-anwendung-api’ (my-application-api) (see figure 1). For example, the ‘meine-anwendung-webapp’ could be used by the frontend and the ‘meine-anwendung-api’ client could be used by the backend services.

screenshot

Figure1: Overview of the clients in the created realm. I have created the clients ‘meine-anwendung-api’ and ‘meine-anwendung-webapp’. The other clients are there by default.

Roles

You can now use roles to control authorisation. They can be assigned to a type or category of user (for example, sales staff). There are three types of roles:

1. Realm role: a global role that is available in every client and can be assigned to every user.

2. Client role: a role that is only available in a specific client and is not accessible from other clients.

3. Composite roles: one or more other roles are linked to a composite role. Users also always have the linked roles of a composite role to which they are assigned.

General permissions are suitable as realm roles and more fine-grained permissions that are used exclusively by the individual clients are suitable as client roles. Figure 2 shows an example overview of possible realm roles.

screenshot

Figure2: Overview of realm roles. The roles ‘offline_access’ and ‘uma_authorization’ are there by default.

Securing a resource using roles

You can now use the defined roles to secure your frontend and backend services directly. Applications based on HTML5/JavaScript can easily integrate the functions of Keycloak through a Javascript adapter. This will help you display the individual areas of your application, for example, using conditional rendering with the following method:

	
	function hatNutzerRole(roleName) {    
		let keycloak = new Keycloak({        
		url: 'http://localhost/auth',        
		realm: 'Meine-anwendung',        
		clientId: 'meine-anwendung-webapp'    
		});    
		return keycloak.hasRealmRole(roleName);
		}
	

Securing bean classes and methods in Java is similarly simple. Access can be restricted or allowed through annotation:

	
	import javax.annotation.security.*;
		@RolesAllowed("administrator")
		public class Ressource {    
		@RolesAllowed("entwickler")    
		public void exampleMethod() {        
		//...    
		}    
		@PermitAll    
		public Object getExampleRessource() {        
		//...    
		}
		}
	

Manage roles efficiently using groups

It is often possible to define groups of users with multiple access permissions, for example according to the structure of a company. You can create these as groups in Keycloak and assign roles to them. You can then assign users to any number of groups. The advantage of this is that you do not have to assign your roles to the users individually, thus saving yourself from maintenance hell (that said, you can also assign roles to users individually). Figure 3 shows an example of the role overview of a ‘Manager’ group.


Figure3: A ‘Manager’ group with the assigned role ‘administrator’. Since ‘administrator’ is a composite role to which the role ‘administrator’ is assigned, these two roles can be seen under Effective Roles.

Users of a group automatically have all assigned roles and thus access to the corresponding resources. Groups are hierarchical so that permissions can be managed in any fine-grained way.

In our example, I would like to define users from different companies. For this purpose, I create a group for each company. There are employees in different areas within the companies. The company ‘Unternehmen_1’ employs managers and developers and the company ‘Unternehmen_2’ also employs sales staff. Developers from the North American region will also have additional access rights. This results in the hierarchy of groups shown in figure 4. Roles can be assigned to these groups as desired to enable fine-grained access authorisation.


Figure 4: An example hierarchy of groups.

Conclusion

Keycloak is a standard IAM system that is easy to integrate. In my blog post, I have given you a brief introduction to the administration of access permissions so that you will be able to apply them in your own context. The basis for this is different types of roles, which can be efficiently assigned to users through groups. Groups are hierarchical, meaning that roles assigned to a group are also available in the groups below it. This allows a fine-grained access authorisation concept to be created. I have explained this to you using a few short examples. There are, of course, a plethora of other exciting topics on Keycloak, but these deserve their own blog posts.

You can find more information on the topic of Keycloak here:

You will find more exciting topics from the adesso world in our latest blog posts.

Picture Daniel Lenzen

Author Daniel Lenzen

Daniel Lenzen studied computer science and has been working for adesso since 2017. He is currently working on a project to develop a platform for digital guarantees.

Save this page. Remove this page.