The Ultimate Guide to Keycloak: Everything You Need to Know

Keycloak is an open-source Identity and Access Management (IAM) tool developed by Red Hat. It provides a comprehensive set of features such as Single-Sign-On (SSO), Identity Brokering and Social Login, User Federation, Client Adapters, an Admin Console, and an Account Management Console. In this tutorial, we will guide you through the basic steps of setting up Keycloak.


Keycloak Installation

1. Install Keycloak

Keycloak can be installed on different platforms. The easiest way to start with Keycloak is by running it as a standalone server:

You can download the server distribution from the Keycloak website ( After downloading and unpacking the archive, you can start Keycloak from the terminal:

cd keycloak-<VERSION>/bin
./ -b

The above command will start Keycloak bound to all network interfaces. Keycloak will be running at http://localhost:8080.

2. Create an Admin Account

To manage Keycloak, you need to create an admin account. Open http://localhost:8080 in your browser, you’ll be directed to the “Create an admin account” page. Provide a username and strong password, then click on “Create”.

3. Create a Realm

Realms are where you manage your groups of users, roles, and applications. Keycloak provides a master realm by default. However, it’s a best practice to create a new realm for managing your application:

  • Click on the “Master” dropdown in the top-left corner and click “Add Realm”.
  • Give it a name and click “Create”.

4. Create a Client

A client in Keycloak represents a resource that users can access. This often corresponds to an application:

  • Click “Clients” in the left-hand menu, then “Create”.
  • Give your client a “Client ID”, this is a unique identifier for the client.
  • Leave the rest of the settings at their defaults for now and click “Save”.

5. Define Roles and Users

Now, you can define roles in Keycloak, and assign users to those roles:

  • Click “Roles” in the left-hand menu, then “Add Role”. Give your role a name and optionally a description, then click “Save”.
  • Click “Users” in the left-hand menu, then “Add user”. Give your user a username, then click “Save”.
  • Now, click “Role Mappings” in the user’s detail page, select the role you created, and click “Add Selected”.

6. Test User Access

You can now test user access to your client:

  • Go back to the details page for your client.
  • Click the “OpenID Connect” link under “Installed Endpoints”.
  • This will give you the URLs your application needs to interact with Keycloak.

That’s it! You now have a basic Keycloak setup. There’s a lot more Keycloak can do – this tutorial has only scratched the surface. You can explore more advanced features like Identity Brokering, User Federation, and Client Adapters in the Keycloak documentation.


What is a realm in Keycloak?

Keycloak is an open-source Identity and Access Management solution aimed at modern applications and services. It provides a multitude of features such as Single-Sign-On (SSO), Identity Brokering and Social Login, User Federation, Client Adapters, an Admin Console, and an Account Management Console.

In Keycloak, a realm is a top-level entity that groups and isolates various security elements. It represents the equivalent of a tenant or an organizational space, where you can manage users, roles, clients, and resources separately.

Here’s what you can manage within a realm:

  1. Users: Individuals that can log in to your applications and services.
  2. Roles: Defined permissions that can be assigned to users.
  3. Clients: Applications and services that rely on Keycloak for authentication and authorization.
  4. Identity Providers: External services that users can use to log in (like Google or Facebook).
  5. User Federations: Integration with external user databases (like LDAP or Active Directory).

Each realm in Keycloak is independent and can have its own users, roles, and configurations. By default, Keycloak creates a master realm that manages Keycloak itself, including defining realm settings, creating users, and more. However, for most scenarios, you will create and use new realms so as not to change or endanger the security of the master realm. This design enables multi-tenancy, as each tenant can have its own realm, isolated from others.


What is Keycloak authentication?

Keycloak authentication is the process through which the Keycloak system verifies the identity of a user who wants to access a system, application, or service.

Keycloak offers a comprehensive suite of authentication mechanisms including:

  1. Username and Password: The traditional form of authentication, where the user provides a username (or email) and a password.
  2. One-Time Passwords (OTP): An OTP can be used for two-factor authentication (2FA) or multi-factor authentication (MFA), where a user is sent a temporary, one-time-use password typically to their email or mobile device.
  3. Identity Brokering: Keycloak can act as a broker between users and external Identity Providers such as Google, Facebook, and Twitter. Users can authenticate with these external providers, and Keycloak will recognize this authentication, allowing the user to access the protected resources.
  4. Single Sign-On (SSO): Keycloak enables SSO, where users can authenticate once and gain access to multiple systems without needing to log in again.
  5. User Federation: This is where an external user database (like LDAP or Active Directory) is linked to Keycloak. It allows for the users’ information and credentials stored externally to be used for authentication.

Keycloak provides a flexible way to manage authentication through Authentication Flows, which are configurable and customizable sequences that control the authentication process. An admin can define different flows and forms, add and arrange authenticators, and apply them to different clients and users as necessary. This makes it very adaptable to various authentication use cases.

Furthermore, Keycloak also provides session management, password policies, and other security features to strengthen the authentication process.

What is user federation in Keycloak?

User Federation in Keycloak refers to the capability of linking an external user database, such as Lightweight Directory Access Protocol (LDAP) or Active Directory (AD), with Keycloak.

This feature allows you to leverage an existing user base for authentication and authorization without the need to import or replicate users into Keycloak’s own internal database. When a user logs in, Keycloak will look up the user in the external database, authenticate against it, and then import the user data into its own database.

User Federation is typically used in scenarios where a large user base already exists in LDAP or AD and you want to avoid having to manually replicate this data into Keycloak. This feature allows Keycloak to manage user access for applications and services, while still utilizing the user data stored in your existing databases.

Keycloak provides built-in support for LDAP and Active Directory and also offers a User Storage SPI (Service Provider Interface) which allows you to write custom code to connect to other user databases.

It’s important to note that while User Federation provides access to users in an external database, it doesn’t provide full synchronization of user data. If you need to regularly sync user data between Keycloak and an external database, you would typically use Keycloak’s Identity Brokering functionality.


What is a Keycloak operator?

Keycloak Operator is a method for packaging, deploying, and managing a Kubernetes application. It follows the Operator pattern, which was introduced by CoreOS, and is now widely used in the Kubernetes ecosystem.

The idea behind the Operator pattern is to encode the knowledge of how to operate an application (like Keycloak) into software that runs inside your Kubernetes cluster. This can automate many tasks that a human operator would otherwise need to perform, such as:

  • Deploying instances of the application.
  • Upgrading the application to a new version.
  • Reacting to failure conditions and attempting to self-heal the application.
  • Scaling the application in response to load.

The Keycloak Operator, in particular, is designed to simplify the deployment and management of Keycloak clusters within a Kubernetes environment. It provides automated procedures for tasks like deploying a new Keycloak cluster, scaling up or down, and backing up and restoring data.

As an operator, it extends the Kubernetes API and encapsulates the complex knowledge of how to manage Keycloak instances within its code. This allows you to manage Keycloak resources using kubectl commands or other Kubernetes tools and makes it easier to integrate Keycloak into a Kubernetes-based infrastructure.


What is Keycloak Redirect URI?

The Redirect URI in Keycloak is a critical security feature that tells Keycloak where to send the user after they’ve been authenticated.

When a client application wants to access resources that require authentication, the application redirects the user to Keycloak for login. After successful authentication, Keycloak will redirect the user back to the application using the Redirect URI.

To ensure the process is secure, Keycloak only redirects users to URIs that have been pre-registered. You set these valid Redirect URIs in the Keycloak admin console when you are setting up your client. The URI typically corresponds to the location of the application that the user will be returned to after authenticating.

A Redirect URI can be a specific URL, or it can use wildcards to represent a range of URLs for more complex applications. For example,* would allow redirection to any path on the domain.

It’s important to configure Redirect URIs correctly, because allowing redirection to arbitrary URLs can expose your application to attacks. A malicious actor could trick Keycloak into sending sensitive data (like access tokens) to a URL controlled by the attacker. By strictly controlling where Keycloak is allowed to redirect users, you can significantly reduce the risk of such attacks.


What is a client secret in Keycloak?

A client secret in Keycloak is a type of credential used for confidential clients to authenticate themselves to the Keycloak server when they request access tokens or authorization codes.

In OAuth 2.0 terminology, which Keycloak uses, clients are applications that want to access a user’s account. They can be either “public” or “confidential”. Public clients are incapable of maintaining the confidentiality of their credentials, such as client-side JavaScript apps or native mobile apps. Confidential clients, however, are capable of maintaining confidentiality, for instance, web applications running on a server.

When a confidential client is registered in Keycloak, a client secret is generated. This secret should be kept confidential and only used when the client application is interacting directly with the Keycloak server. For instance, during the Authorization Code Flow, the client application exchanges the authorization code for an access token and authenticates itself using the client secret.

The client secret can be viewed and regenerated from the Keycloak administration console, under the ‘Credentials’ tab of the client’s settings. As a best practice, this client secret should be stored securely and not exposed to the public or included in client-side code.

What is the grant type in Keycloak?

In Keycloak, which is an open-source Identity and Access Management (IAM) solution that supports both OpenID Connect (OIDC) and OAuth 2.0, a grant type refers to the way an application gets an access token.

OAuth 2.0 defines several grant types, including but not limited to:

  1. Authorization Code: This is used by web and mobile apps. It involves redirecting the user to the authorization server (Keycloak, in this case), and then they are redirected back with an authorization code. That code is then exchanged for an access token.
  2. Implicit: This is a simplified flow optimized for in-browser clients (such as single-page apps), where the access token is returned directly without requiring an intermediate authorization code.
  3. Resource Owner Password Credentials (ROPC): With this, the user provides their service credentials (username and password) directly to the application, which uses them to obtain an access token from the authorization server. It’s generally not recommended unless other flows can’t be used.
  4. Client Credentials: This is used when clients want to access resources independently of any user interaction, typically for server-to-server communication.

In the context of OpenID Connect, there’s also:

  1. Hybrid: This is a combination of the above flows to provide additional flexibility. For example, the authorization code and implicit grants can be combined to provide an id_token (which can be validated immediately) and an authorization code (which can be swapped for an access token securely server-side).
  2. Refresh Token: If allowed, clients can use a refresh token to get a new access token without requiring the user to authenticate again. Refresh tokens can be issued alongside the access token following a user’s successful authentication.

The specific grant type(s) a client uses are configured within the Keycloak admin console in the client’s settings. It’s important to select the correct grant type for your use case, considering both the user experience and security implications.

What is Keycloak in Kubernetes?

Keycloak is an open-source Identity and Access Management solution developed by Red Hat, which can provide authentication and authorization services for applications.

When Keycloak is used in Kubernetes, it provides a way to secure applications and services that are deployed within your Kubernetes cluster. It allows you to centrally manage and enforce authentication and authorization policies for your applications, rather than having to handle these concerns within each individual application.

The typical deployment of Keycloak in Kubernetes involves running the Keycloak server in a container within a Pod. You can manually configure such a deployment, or you can use the Keycloak Operator, which simplifies the process of installing, managing, and maintaining Keycloak on Kubernetes.

The Keycloak Operator is a Kubernetes Operator, which is a method of packaging, deploying, and managing a Kubernetes application. Using the Keycloak Operator, you can define a Keycloak custom resource in Kubernetes, and the Operator will take care of deploying Keycloak, configuring databases, setting up services and routes, and other necessary tasks.

Once Keycloak is running within your Kubernetes cluster, you can configure your applications to use it for authentication and authorization. This usually involves configuring your applications as clients within Keycloak, and then implementing an OAuth2 or OpenID Connect flow within your application to handle user logins.

So, in short, Keycloak in Kubernetes provides a centralized, automated way to handle user authentication and authorization for your Kubernetes applications, making it an important component in a Kubernetes-based microservices architecture.

What is a Keycloak adapter?

Keycloak adapters, also known as client adapters, are libraries that you can include in your application to make it easy to secure your applications and services with Keycloak. They provide integration with different platforms and frameworks.

These adapters take care of redirecting to Keycloak for login, dealing with tokens, securing application endpoints, and other necessary tasks. This allows you to offload a lot of the security-related work from your application code to the adapter, simplifying your application and reducing the potential for security mistakes.

Keycloak provides adapters for a variety of platforms and environments, such as:

  1. Servlet Containers (like Tomcat)
  2. Java EE servers (like WildFly, JBoss EAP, and others)
  3. JavaScript applications (with Keycloak.js)
  4. Node.js applications
  5. Spring Boot applications
  6. Quarkus applications

Each of these adapters integrates with the security mechanisms of the underlying platform or framework, and provides a Keycloak-centric API for controlling authentication and authorization.

To use an adapter, you generally need to include the adapter library in your application, add some configuration to tell the adapter where your Keycloak server is and how to authenticate itself, and then use the adapter’s API to secure your application’s resources. The specifics of this process can vary depending on the platform and adapter in question.

Dive into this insightful post on CodingReflex to unlock the power of Quarkus, Java’s revolutionary framework for building ultra-speed applications.

  • For real-time updates and insights, follow our tech enthusiast and expert, Maulik, on Twitter.
  • Explore a universe of knowledge, innovation, and growth on our homepage, your one-stop resource for everything tech-related.

For more information on related topics, check out the following articles: