Step By Step Guide To Setup Keycloak Configuration For Tornjak

Introduction to Tornjak + IAM Integration

Tornjak is an open-source project under the CNCF (Cloud Native Computing Foundation) umbrella that uses the SPIFFE/ SPIRE architecture to provide a “zero trust security architecture’’ and builds on top of this architecture to simplify the identity workload management framework across deployments. To learn more about Tornjak, refer to these two detailed blogs: Shepherding your Cloud Native “cattle” with Tornjak and Tornjak Open Source Project — Management Framework for Workload identities (“ZERO TRUST”).

Figure 1: SPIFFE and SPIRE Logo

Without user management, if one knows the URL or access point of Tornjak, anybody can access the Tornjak application and indirectly SPIRE Server. This is the primary motivation for why we introduced Identity Access Management (IAM) to Tornjak by using Open Authorization (OAuth 2.0) protocol. We did not want to redesign and rediscover the user management and the boilerplate that it comes with. Therefore we selected one of the open-source Identity and Access Management solutions named Keycloak. Our design is not restricted to a specific product, like Keycloak. It works with any IAM supporting OAuth 2.0. To read more on the architecture of IAM integration with Tornjak refer to this blog.

Figure 2:

Why Keycloak and What is it?

Keycloak is an open-source Identity Access Management (IAM) solution that allows management of users, their roles, and privileges for accessing a specific system and applications. Some of the reasons Keycloak is chosen to secure Tornjak include:

• It is an open-source solution, which means it lends flexibility and agility for future development
• It allows performing authentication and authorization by using different authorization flows
• It has plenty of customizable features including single sign-on, management of federations, customizing clients, and specifying users and their roles
• It supports standard protocols such as OIDC (OpenID connect), OAuth, and SAML (Security Assertion Markup Language).

Regarding standard protocols, in general, it is recommended to use OIDC as it is designed to work with the web and is easier to implement on the client side. Tornjak project uses OIDC because it is designed to work with the web HTML5/ JS, it is easier to implement on the client side than SAML, and in OIDC tokens are in JSON format which makes it easier to be consumed by JavaScript applications.

Figure 3: Tornjak Logo and Keycloak Logo

Setting Up and Running Keycloak Instance

You have many options to configure and run a Keycloak instance. Refer here to explore those options. For this guide, we will use Docker to run the Keycloak instance in a docker container. Make sure you have Docker installed before proceeding with this step. You can follow the instructions here for installation. After installing docker. On your terminal run the following command:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=”username” -e KEYCLOAK_ADMIN_PASSWORD=”password” quay.io/keycloak/keycloak:19.0.1 start-dev

By replacing “username” with a Keycloak admin username and by substituting “password” with a Keycloak admin password, one can set credentials for a Keycloak admin to run the Keycloak instance. This will run Keycloak in a Docker container making the server available on port 8080 locally.

Next, go to http://localhost:8080 and you should be able to access the Keycloak server. Here you can view the documentation as well as access the Administration Console as you can see below.

The Administration Console helps you manage all aspects of the Keycloak server in one place.

Figure 4:Keycloak Server Access UI

Next click on the Administration Console. You will next be redirected to the console as you can see below and asked for the credentials to log in as a Keycloak admin.

Figure 5: Keycloak Server Login Page

Username: username
Password: password

Enter the credentials you used to create the Keycloak instance above and click sign in.

Easiest Way to Configure Keycloak

Once you log in, you will see a Master Realm with the server info and features.

Figure 6: Keycloak Administration Console

• Click on the “Master” realm drop-down on the top left side of the console as you can see below
• Click on “Create Realm”

Figure 7: Create Realm Page

• Download the example “Tornjak-keycloak-realm-import.json” from https://github.com/spiffe/tornjak/tree/main/examples
• Next to Resource file, click browse and upload the JSON file
• Make sure Enabled is set to On, as a realm that is not enabled can not be used
• Click on Create

Figure 8: Tornjak Realm Import Using JSON

• Once the realm is created, you will see the realm name on the top left side of the console as you can see below. Here is where you can switch between different realms you created and visualize the Master Realm settings.

Figure 9: Tornjak Realm Page

The above step will import all resources except users. To create users, skip to the “Creating And Registering Users” section. After completing that step you are good to go.

To understand the concept of Keycloak and to use the other options to create a realm follow the steps below. If you used the above step to create your realm you can skip to the “Creating And Registering Users” section.

Creating and Configuring Realm

A Realm is the core concept in Keycloak. It’s a container within Keycloak to manage clients. A Realm manages and secures security metadata for a set of users, applications, and registered OAuth clients. The Master Realm is the central realm that manages all other realms and is specific for Keycloak configuration. The Master Realm should not be used for your specific application. To manage your application a new realm should be created.

For our Tornjak Application, we will be creating a “Tornjak” realm.

To create a new realm follow the steps below:

• Click on the “Master” realm drop-down on the top left side of the console as you can see below
• Click on “Create Realm”

Figure 10: Keycloak Administration Console

• Give the realm, a “realm name” — e.g. tornjak
• Make sure Enabled is set to On, as a realm that is not enabled can not be used

Figure 11: Create Realm Page

• Click on Create
• Once the realm is created, you will see the realm name on the top left side of the console as you can see below. Here is where you can switch between different realms you created and visualize the Master Realm settings.

Figure 12: Tornjak Realm Page

After you create the realm, you have two options to create the realm resources. The easiest way is by using the import feature, another way is by manually adding each resource in the Keycloak console. In this blog, we will be using the import feature. If you are interested in configuring resources manually, follow the documentation here.

• To import Tornjak realm resources download this JSON file. And go to Realm Settings.

Figure 13: Tornjak Realm settings page

• In the top right section, under Action click on Partial Import

Figure 14: Realm Import Page

• Here, you can import your realm resources by clicking on browse and importing your resource file, as you can see below.

Figure 15: Imported Tornjak Realm JSON

• Select and check all the resources to import. You can also edit the JSON format in the window. Additionally, you can select the appropriate operation in case the resources already exist. Select Skip.
• Click Import, and you will see the resources imported as “Added” under the Action column including the realm resource info such as the Type, Name, and ID of the resource imported.

Figure 16: Realm Imported Resources Window

• Click on Close

Importing Tornjak realm with the above step, the following resources will be imported [each resource will be discussed in detail in the following sections]

- Realm metadata including realm roles
- Client metadata including client roles
- Group metadata and relationship
- Scope Mappings

• If you imported all the resources using the above step, your realm is configured and you are “almost” good to go.
• At this point, we just need to configure the redirect_uri and we should be able to hook up Tornjak.

There are two redirect URIs:

The first URI is the Valid redirect URIs, this is an access point to the Tornjak application. If the application is run locally such as on (minikube or kind) this will be localhost, which is already imported for you through the import feature. But if Tornjak runs on the cloud, it would be an ingress value of the service. [This is the URI you want Keycloak to redirect to after successful login]

The second URI is Valid post logout redirect URI, this is the URI you want Keycloak to redirect to after successful logout.

To set up the redirect URIs:

• While still in tornjak realm, go to your client by clicking on Clients > Tornjak-React-auth and scroll down to Access settings

Figure 17: Add redirect_uris

• Under Access settings, click on the +Add valid redirect URIs icon in theValid redirect URIs section and add your application’s ingress/ URI. IMPORTANT: Make sure you add /* after your application URI— e.g. http://example.cloud/*, if you did not add /* after the URI you will receive the following error.

Figure 18: Invalid redirect_uri

• Repeat the same step for Valid post logout redirect URI

Figure 19: Ingress value added for redirect_uri

Now your Tornjak application is up and running. If you go to your localhost or ingress URI where you are running your application you will be redirected to the Keycloak login page.

Figure 20: Keycloak Login Page redirect

The only step remaining is setting default groups/ roles and creating/ registering users to login into the Tornjak application.

Setting Default Tornjak Viewer Group

To set Default Groups and default roles to users when they register:

• Go to the User registrationtab under “Realm settings”
• Click on Default groups
• Add your default group [In our case add “Viewer-group” group as default] this will make viewer group default for all users

Figure 21: User Registration Realm Settings Page

Follow the steps below to create or register new users.

Creating And Registering Users

Users can self-register through the Tornjak application if User registration is enabled under “Realm settings” > “Login”. By default, every user has read-only access, when they register initially. And Keycloak admin can give admin roles to a Tornjak admin user that is already registered through the Tornjak Application.

Another way users can be registered is by the Keycloak admin, and we will be using this option for this blog.

To register a user:

• Select Tornjak realm
• Under “Users”
• Click on “Create new users”
• Type in “Username”, “Email”, “First name” and “Last name”
• Make sure the user is enabled, by toggling the Enabled flag to ON (As a disabled user can not log in)

Figure 22: Create User Page

• Assign a group, by clicking on Join Groups and selecting from available groups

Figure 23: Select Group to Assign to User Page

• Click onCreate

Figure 24: Created Users Page

Then assign the password:

• Select theCredentials tab

Figure 25: User Credentials Page

• ClickSet password
• Enter the password, adjust Temporary as needed, to force the user to create a new password on the next login (recommended)
• Select Save to create

Figure 26: Assign Password to User Page

Using the above steps, create two users and assign them to the following groups:

• adminuser — assigned to the “admin” group
• vieweruser — assigned to “viewer” group (if “viewer group is set to default under “Realm settings > “User registration” skip this step)

- Viewer/ Non-Admin Users — Can not make changes or access exclusive information

- Admin — Be granted administrative privileges and access information accordingly

Refer to the documentation here to see which APIs an admin user and a viewer user can access.

That is it. Now you can use the credentials you created above to login into the Tornjak Application.

Sign in with the username and password you created as a Keycloak admin, and you should be able to access your application either as a viewer or tornjak admin depending on the user you signed in with.

If signed in with an admin user, you should be able to see the admin portal as shown below.

Figure 27: Tornjak Admin Console

If signed in with a viewer user, you should be able to see the viewer portal as shown below.

Figure 28: Tornjak Viewer Console

Here is a video on how to create users with specific roles.

The next sections are detailed optional Keycloak-specific configurations.

Creating and Configuring Client

Within a realm, you can create clients to secure your application.

A client is a service that is secured by a realm. Clients can be runtime components talking to Keycloak such as a web frontend code in a browser, mobile frontend code in a React Native app, API server, etc. You will often use a Client for every Application secured by Keycloak.

For our Tornjak application, we will be creating one client for the frontend react application to talk to.

If you have used the above import feature to import the Tornjak realm, the Tornjak client is already imported and configured as well. Therefore you can skip to the next section.

If you would like to import your client separately, the easiest way to import your client is by using a JSON file. To create the Tornjak client download this file. And import to Keycloak by clicking on Import client. This will send you to an Import client page, where you can browse locally and import.

Figure 29: Import Client Page

After you open your file in the Keycloak console, you will be able to see all settings imported on your console including the JSON format as you can see below.

Figure 30: Tornjak Imported Client Page

If you are interested in creating a client manually, follow the documentation here.

• Here you can set the “Client type” — which can be “OpenID Connect” or “SAML”

“OpenID Connect” allows Clients to verify the identity of the End-User based on the authentication performed by an Authorization Server.

“SAML” enables web-based authentication and authorization scenarios including cross-domain single sign-on (SSO) and uses security tokens containing assertions to pass information.

You can also choose different authorization flows:

Standard flow enables standard OpenID Connect redirect-based authentication with an authorization code. In terms of OpenID Connect or OAuth2 specifications, this enables support of ‘Authorization Code Flow’ for this client.

Authorization flow with public access is chosen to support redirects after login and logout sessions

With the authorization flow, the user is sent to the Keycloak login page when accessing the application and is allowed to log in with credentials or register for a new account

Assigning Realm Roles and Client Roles

Roles are special privileges given to a user to access your application. Realm roles are specific to your realm as client roles are specific to the client. But realm roles can be mapped to client roles to associate roles or allow inheritance. To learn more about Roles check this link.

If you used the import feature to import your realm, you have imported two roles “Admin” and “Viewer” roles for the Tornjak client.

• Viewer/ Non-Admin Users — Can not make changes or access exclusive information
• Admin — Be granted administrative privileges and access information accordingly

The following are the roles that are imported:

For Realm Roles:

tornjak-admin-realm-role
tornjak-viewer-realm-role
NOTE: Currently, the naming convention for these roles is a requirment for the backend.

For Client roles:

admin (map to tornjak-admin-realm-role)
viewer (map to tornjak-viewer-realm-role)

If you want to create more roles, or create your roles manually. Follow the steps below.

To create a Realm role:

• Under your realm (Tornjak) > Realm roles

Figure 31: Realm Roles Page

• Click on Create role
• Give your role a “Role name” (e.g. tornjak-admin-realm-role)
• Give your role “Description” (Optional)
• Click Save

Figure 32: Realm Create a Role Page

Figure 33: Realm Created Roles Page

To create a Client Role:

• Click on Clients > (Tornjak-React-auth) option
• Go to the “Roles” tab:
• Click on “Create role”
• Give your role a “Role name” (e.g. admin)
• Give your role “Description” (Optional)
• Click Save

Figure 34: Client Create Roles Page

Figure 35: Client-Created Roles Page

To Map Realm and client Roles

• After your client role is created
• Click on Action on the top right of the console

Figure 36: Client Associate Roles to Realm Roles Page

• Under “Action”, select “Add associated roles”
• Select the realm role to be mapped
• Map “tornjak-admin-realm-role” to “admin” role etc.
• Select Add to save

Figure 37: List of Available Realm Roles to Map to Client Roles

Creating Groups

Groups and Roles have a similar purpose. They both give users special and specific permissions or access to use the application in a certain way. Using Groups you can apply multiple roles to a user or group of users and make the role-assigning process efficient and easy. To learn more about Groups check this link.

If you followed the above step on importing the realm, the groups are also imported. Therefore, you can skip this step. But if you want to create more groups. Follow the steps below.

To create Groups:

• Under your realm (Tornjak) > Groups
• Click on Create group
• Give your group a “Name” (e.g. Admin-group)
• Click Save

Figure 38: Create Group Page

• Select the group name from the list
• Under the “Role mapping” tab, map the role/s associated with the group using “Assign role”
• E.g. assign roles to the “Admin-group” account, select “tornjak-admin-realm-role”
• Press Assign

Figure 39: Role Mapping to Group Page

Figure 40: Created Groups Page

Now one can assign these groups to users accordingly.

Adjusting Optional Settings Under Realm Settings

There are some useful realm settings to adjust. For the selected Realm Tornjak, Select “Realm settings” under the “Configure” sub-section on the left side of the panel:

• Go to the Login tab
• Toggle ON User registration— which allows users to register through your application
• Toggle ON Forgot password— which allows users to reset and retrieve forgotten passwords
• Toggle ON Remember me— which helps users remember forgotten passwords
• Toggle ON Edit username — which allows the Keycloak admin to edit the username already set otherwise it is read-only

Figure 41: Realm Settings Page

Conclusion

Tornjak is an open-source project actively under development. If managing workload identities in the current world is of interest to you we are always looking for people to contribute, share ideas, and comments or give Tornjak a go. For more information on Tornjak check out the GitHub repo, and YouTube Page.

References:
Keycloak's official website: https://www.keycloak.org/
SPIFFE/ SPIRE official website: https://www.spiffe.io/
Tornjak Keycloak Documentation: https://github.com/spiffe/tornjak/blob/main/docs/keycloak-configuration.md

Tornjak Team

Mohammed Abdi — Tornjak Contributor (Medium: Mohammed M. Abdi, SPIFFE Slack: Mohammed Abdi)

Maia Iyer — Tornjak Contributor (Medium: Maia Iyer, SPIFFE Slack: Maia Iyer)
Mariusz Sabath — Tornjak Maintainer (Medium: Mariusz Sabath, SPIFFE Slack: Mariusz Sabath)

Thanks to Maia Iyer and Mariusz Sabath