What is Keycloak? How to use it — an example with nodejs? (Part 1)
As our world evolves towards getting more and more digital, our digital identities become more and more important, and with it, the means to verify them accurately.
What this means for software products is that they have to manage user identification and
access securely and concretely. But this isn’t easy right? I mean, as a business product manager, you would want to focus more on feature development and intrinsic value addition rather than solving already solved problems, as a friend once told me. I didn’t quite agree then, but eventually you should recognize the work done by others and welcome their ideas and work rather than always building everything from scratch.
On a similar note, I would say that building a native Identity Management and Access Control solution may seem intriguing, but if you have other important areas to work on, leave this to the pros — Keycloak.
Keycloak is an Identity and Access Management(IAM) Software, which will act as an essential tool in your business product. IAM typically aims to verify the identity of a user or system which is requesting access to your environment, and evaluates a set of rules which tells what features and assets is that user/system has access to. The identity management and access management are two different entities. In classical situations, access management relies on an Identity Provider to verify the user, and builds on top of it to map the identity of the user/system with what it can do in an environment. Typically Role Based Access Control(RBAC) is a standard concept that is followed to establish an access control layer. A support layer is added to make use of this access management, basically a set of protocols to use this with other applications. Usually the protocol ends up being OAuth, which is a standard responsible for managing the access control parameters on the Authorization software side, as well as lay the guidelines to be followed by the applications utilizing the Authorization service.
If you wish to know more about IAM, you can refer to the following article, or other articles online:
I will move on to explain where Keycloak fits into the picture. Keycloak combines the power of a Identity Provider and a Authorization Server to give a foolproof IAM solution to us. Also it has out of the box integrations with social logins sites, other identity providers, as well as federate external user databases like LDAP servers. Keycloak thus seems like a software that we would want to use to reduce our IAM overhead.
Installation
Before we delve into the using Keycloak, I should tell you how to set it up quickly. I will suggest a docker installation available in your local, and we can use the docker image for keycloak easily.
$ docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:latestThere are other ways to set it up, visit Keycloak’s Getting Started Guide.
After the server is up and running, you can open the browser at http://127.0.0.1:8080/auth/ and click on Administration Console, which should redirect you to http://127.0.0.1:8080/auth/admin/master/console/. Log in to the master console with username password that you provided above(admin, admin for me).
After we login, we can see the following page —
Let me explain what a realm is before we proceed. Keycloak tells us to think of a realm as an equivalent of a tenant. This can also be thought of as a namespace(if you are familiar with networks).
Realm Creation
Hover on the Master(realm) in the top right and select Add Realm. Here we create our new realm which is dedicated to the product that we are building-
Click on the create button and you should see the realm’s home page —
Let me explain the side menu bar’s configure section quickly.
- Settings is to tune the realm settings like token expiry, themes, cache etc.
- Clients is an important tab, and is used to create clients which represent the applications that we build for our product.
- Client scopes are common scopes that clients can use. Scopes are entities that help the clients(applications) in their decision to grant or deny access to it’s resources(assets).
- Roles are common set of classification which help majorly in granting access to certain applications’ assets. These can be used commonly across all the clients.
- Identity Providers leverages the ability of external identity management systems to authenticate.
- User Federation is to integrate Keycloak’s identity database with external User Databases like ldap servers.
- Authentication is to control Keycloak’s default authentication/ authorization behavior. For most of the cases you won’t need to tweak this, as it is a slightly advanced feature for real fine tuning purposes.
The manage section is fairly intuitive, where you can create and manage users, groups and sessions; and do imports and exports of settings. Events tab is to check the admin and user logs(like logins, changes etc) and add plugins that you write for Keycloak.
Sample Application with Nodejs
Keycloak configuration
Now that we are ready with our basic Keycloak console, let us build a basic application to feel this whole thing in action. Before we start with our nodejs code, let us complete our Keycloak setup.
First, let us create 2 roles, user and admin. Select the roles tab, and click on add role button —
Create admin in the same way(name it “admin” exactly for the purpose of this tutorial).
Now let us create an user. Go to users tab and click on add user button —
Now we set his password(credentials), by clicking on the credentials tab —
We now move on to assigning a role to our user, click on Role Mappings tab —
Note that the roles we had earlier created is displayed here. Click on add selected to actually add the highlighted role(don’t add the admin role, we will want to see a denial of service due to the lack of this role for this user).
Now that we are ready with our user and have assigned him his role, lets move on to creating a client for our nodejs application(which we will code in a bit). Go to Clients tab and click on Create button —
Additionally, let us edit some properties of this client after its created —
I would like to emphasize on the access type selection here. Notice that we changed the default(which is public) to confidential type. A brief overview of the types:-
- Public client: When we cannot transmit client secrets over the channel to the application. For example in the case of browsers and mobile applications. Because each instance of a browser tab of mobile application is different and, and is almost always over public internet, we cannot pass a secret to them; and also there is a issue of trust, because the end user can have access to the secret if transmitted to his/her application(browser/ mobile etc).
- Bearer-only client: When we want our backend application to simple verify the token and get details on the scopes of the issued token, not have a fine grained access control on the particular application. Doesn’t have any resources(assets) associated to it.
- Confidential client: When we want a fine grained access control feature enabled by the keycloak server on the client application(running in the backend). Has resources(assets) associated to it.
There are two important distinguishing factors, or say two categorizations between these 3 client types. First is public clients are used for user-end devices and not servers whereas the other two are used more often for backend services(servers side applications). The other important categorization is the ability of confidential clients to register resources on which it can perform fine grained access control using scopes, policies and permissions(its a really very powerful feature); this feature is not available for public and bearer-only clients.
Now that we understand these types, we will resume creation of our client with confidential type, and authorization enabled(service account is auto enabled with this). Enabling authorization actually enables us to define and use the fine grained access control that I mentioned. Save the client configuration, and you will see Authorization tab enabled at the top. Click on it, you will see the following —
Let me explain the function of each of the sub top navigation tabs of Authorization before me move ahead —
- Resources: Manage resources, i.e. assets, of the application. This is the abstraction of the actual assets that the application(whose client this is) consists.
- Authorization Scopes: These are resource specific scopes that we can define to become part of our access control. This differs from the common Client Scopes which we saw earlier in the sense that these scopes hold meaning only in the context of this particular application’s resources, and not others. For example if we have 2 clients: client-1 with resource-1 and client-2 with resource-2; a scope say “read” would hold different meaning in the case of resource-1 and resource-2, based on how that application is actually written.
- Policies: These are the actual conditions that must be satisfied to return a permit object.
- Permissions: These bind policies to whole resources or specific scopes, to represent a wholesome permit/deny evaluation. This means that it links a policy(which is essentially a boolean logic) to an asset(or a part of it), providing the ultimate fine grained control that we spoke about.
Now that we have a brief understanding of what Authorization is all about, let us create a authorization configuration for the application that we are building. Click on Authorization Scopes and then click create —
Similarly create a write scope(ensure it’s name is exactly “write” for the sake of our tutorial). Now click on Resources tab and click on create —
Notice that we are associating read and write scope to this resource. Now click on Policies, click on Create Policy and select Role in the dropdown —
Notice that we are associating different realm roles to these policies, defining our logic of grant evaluation.
Lastly, lets link these Resources, scopes and policies together! Click on Permissions tab and click on Create Permission and select Scope-Based from the dropdown —
Notice how we bind a resource, its scope and the desired policy to create a permission, which becomes our evaluation logic for granting access.
Before we finish, let us test the configuration we made so far. Yes it can be done via the UI! Isn’t it great? Click on Evaulate tab, selecting the client, user and resource, scope and then clicking evaluate results in —
We have reached the end of this article, and to continue with our tutorial of building our nodejs application, I will continue onto the next article of this series(Part 2). Thankyou for reading this far, hold on a bit longer to see all this hard work and concepts crunching bear fruits.
Continue reading Part 2 —
Read more on the how to use Keycloak in a production environment with multiple microservices here (from the author of this series) —
