Blogs Infinispan Insights, securing Infinispan with Keycloak

Infinispan Insights, securing Infinispan with Keycloak

Infinispan Insights: Securing Infinispan with Keycloak

This tutorial shows you how to secure your Infinispan cluster using Keycloak. To understand the basics of Infinispan Security, check this blog post before.

Key Points:

  • Learn how to create a security realm in Keycloak.

  • Override the default security realm in Infinispan.

  • Authentication and authorization in Infinispan with Keycloak.

Infinispan and Keycloak in a nutshell

About Infinispan

Infinispan is an open-source, in-memory distributed key/value data store. It is designed to provide fast and scalable access to frequently accessed data by storing it in memory. In addition to caching, Infinispan offers features for data distribution, replication, and partitioning, making it suitable for use in distributed and clustered environments.

Infinispan is often used in scenarios where low-latency access to data is critical, such as caching frequently accessed database queries, session data in web applications, or other use cases where quick access to data can improve overall system performance

About Keycloak

Keycloak is an open-source identity and access management solution developed by Red Hat. It provides functionalities for identity and access management, including features like single sign-on (SSO), user authentication, authorization, and user federation. Keycloak is designed to simplify the implementation of security protocols and standards such as OAuth 2.0, OpenID Connect, and SAML. Some key features include Single Sign-On (SSO), Identity Brokering, User Authentication, User Federation, RBAC and more.

Infinispan and Keycloak

Keycloak uses Infinispan as its underlying data store for caching and storage purposes. Infinispan provides scalable and efficient caching of authentication and authorization-related data. This helps improve performance and responsiveness, especially in scenarios where quick access to user session information and other identity-related data is crucial.

Some ways Keycloak leverages Infinispan include Caching User Sessions, storing Authorization policies, providing distributed caching, improving performance, failover recovering and more.

What about Infinispan leveraging Keycloak ?

Infinispan provides several ways to handle authentication and user management. By default, the security realm is properties based. However, token based authentication is supported and Keycloak can be used for that purpose.

Creating a Security Realm in Keycloak

Run Keycloak in dev mode

The easiest way to use Keycloak on your laptop is in a container using the development mode. Because we’re going to run Keycloak in one container and Infinispan in another, let’s set up a network to connect them.

For Linux users, there’s an option called network_mode: host that might be available to you instead of using a network bridge. However, since this option doesn’t work for Mac or Windows currently, we’ll focus on the method that suits all operating systems.

docker network create -d bridge mynetwork
docker run -p 8080:8080 --network=mynetwork --name=keycloak -e KEYCLOAK_ADMIN=keycloak -e KEYCLOAK_ADMIN_PASSWORD=keycloak start-dev

Keycloak Image will create an administrator user by defining the KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD environment variables.

After getting the container up and running, go to http://localhost:8080 Click on the Administration Console link, and log in using the credentials "keycloak/keycloak".

Admin Keycloak

Create a realm

Keycloak realms are a fundamental concept in Keycloak. Realms in Keycloak serve as a way to isolate and manage different sets of users, applications, and their associated configurations.

Using the web administration tool, create a new realm called "Infinispan". This realm is what the Infinispan Server will use in the later steps of this tutorial.

Keycloak create realm

Name your realm “infinispan”.

Keycloak: realm name is infinispan

Create the Infinispan clients

Clients are entities that can request authentication of a user. Clients come in two forms. The first type of client is an application that wants to participate in single-sign-on. These clients just want Keycloak to provide security for them. The other type of client is one that is requesting an access token so that it can invoke other services on behalf of the authenticated user.

For the Infinispan Server and testing the Console security, we’ll require two clients set up in Keycloak: one named "infinispan-console" and the other "infinispan-server".

Infinispan Console Client

Create a Keycloak client named “infinispan-console”. The Infinispan Web Console uses this client to authenticate console users with Keycloak in order to obtain an authentication token. This token is then used to authenticate all requests by the console to the Infinispan server.

Keycloak: infinispan-console client step 1

Configure the valid redirect URIs with Infinispan’s console URI: http://localhost:11222

Keycloak: infinispan-console client step 2

This step is completed.

Infinispan Server Client

Create a second client called "infinispan-server". Set "client authentication" to "ON". This defines the type of the OIDC client. When it’s ON, the OIDC type is set to confidential access type. When it’s OFF, it is set to public access type ("infinispan-console" client type).

Keycloak: infinispan-server client step 2

This step is completed.

Create a user

Once we have the two clients created, we need to create an admin user for Infinispan.

Click on the "users" menu, and create a user named "admin".

Keycloak: create admin

Once the user admin is created, navigate to the user detail page.

Keycloak: admin detail

In the credentials tab, create a password for the user, for example, "adminPassword".

Keycloak: admin set password

We are now ready to run Infinispan.

Running Infinispan secured with a Keycloak realm

Create the Infinispan security realm configuration

You can configure this in XML, JSON, or YAML. In the example provided below, the configuration is in YAML format.

Create a file named infinispan-token-realm.yaml with the following content.


     - name: default
         name: infinispan
         authServerUrl: 'http://keycloak:8080'
         client-id: infinispan-console
           clientId: infinispan-server
           introspectionUrl: 'http://keycloak:8080/realms/infinispan/protocol/openid-connect/token/introspect'

We are not done yet!!

Read the following sections to understand and change the placeholders in the file.

Default Security Realm name

The security realm is named "default". This file is designed to replace the default security realm in Infinispan, which is originally based on properties, with the configuration for this token-based realm.

Client Secret

Retrieve the secret for the "infinispan-server" client from the Keycloak Administration, and then paste the secret value into the file replacing 'COPY AND PASTE THE SECRET FROM KEYCLOAK'.

Keycloak: grab secret

Authentication Server URL - authServerUrl

The authentication server is Keycloak, and it’s running at localhost:8080. However, in the YAML configuration above, we used "keycloak" instead of "localhost" (the container name). This adjustment is needed when running containers in a Docker network. The Infinispan Server will be reaching out to the Keycloak Server inside the Docker environment. As mentioned earlier, Linux users can use "localhost" with the network_mode: host configuration.

Run the Infinispan Server overriding the default security realm

Lets run Infinispan in a container providing the created security realm configuration.

docker run -it -p 11222:11222 -v $(pwd):/user-config
-c infinispan.xml
-c /user-config/infinispan-token-realm.yaml

The command:

  • Creates a volume "user-config" in the current directory where we created the file infinispan-token-realm.yaml

  • Attaches the container to the network "mynetwork" so Infinispan and Keycloak can connect

  • Uses -c, which means the container is using the default configuration file, infinispan.xml. Yet, specifying another -c file, it adds the content of infinispan-token-realm.yaml to infinispan.xml. Since this file configures the default security realm, the original Infinispan default properties realm will be replaced with the token-based realm.

Verify the changes

Accessing the following URL provides the information used by the Infinispan Web console to handle authentication.

   "mode": "OIDC",
   "clientId": "infinispan-console",
   "ready": "true",
   "realm": "infinispan",
   "url": "http://keycloak:8080"

The Infinispan Console will use the information above, and making use of the Keycloak Javascript Adapter, the interface will redirect to Keycloak for user authentication.

Connect to the console with the admin user

Go the console web URL: http://localhost:11222

This site can’t be reached

The console needs to access Keycloak from outside the container. However, the realm configuration uses keycloak host.

Site not reached

To avoid this issue, the workaround is simple: add to the following line to the /etc/hosts file:      keycloak

As mentioned before, If you are using linux you can avoid this by using localhost and running both containers with network_mode: host.

Authenticate using Keycloak

When opening the Infinispan Console, Infinispan will attempt to make a call to a REST API that requires authentication. You’ll be redirected to the Keycloak authentication, where you should use the credentials admin/adminPassword. When you initially connect as admin, you’ll be prompted to change the password. For this example, you can stick with "adminPassword".

Infinispan: authenticate with Keycloak

After Keycloak redirects back to the Infinispan Console, you can verify that admin is authenticated. However, you will encounter Unauthorized errors in the console interface, since the connected user’s roles are not known by Infinispan.

Admin has not admin role

Create and assign Infinispan ADMIN role

To grant complete access to the admin user, it’s necessary to create a role named "admin" and assign that role to the user in Keycloak.

Create the ADMIN role in Keycloak

Open the Keycloak administration interface, click on "Roles", and then create a role with the name "admin".

Keycloak: create admin role

Assign the ADMIN role in Keycloak

In the admin user detail page, go to the Role Mapping tab and assign the previously created "admin" role there.

Keycloak: assign admin role to admin user

Return to the Infinispan Console, and you’ll notice that the admin user is now granted the admin role in Infinispan as well.

Infinispan: admin is granted

To go further

In the Infinispan Simple tutorials repository you will find an example with docker-compose, for Linux and non linux users. There are many other advanced features in Keycloak, this is just the most simple use case.

Learn more about it in the Keycloak and Infinispan documentation.

Get it, Use it, Ask us!

We’re hard at work on new features, improvements and fixes, so watch this space for more announcements!

Please, download and test the latest release.

The source code is hosted on GitHub. If you need to report a bug or request a new feature, look for a similar one on our JIRA issues tracker. If you don’t find any, create a new issue.

If you have questions, are experiencing a bug or want advice on using Infinispan, you can use GitHub discussions. We will do our best to answer you as soon as we can.

The Infinispan community uses Zulip for real-time communications. Join us using either a web-browser or a dedicated application on the Infinispan chat.

Katia Aresti

Katia Aresti is a Senior Software Engineer working for Red Hat since 2017. She is part of the core Infinispan team, reponsible of the integration with other frameworks such as Spring-Boot, Vert.x or Quarkus, developing new features such as Clustered Counters, REST API endpoints and the new Server Web Console.