SSO on microservice architecture. We use Keycloak. Part number 1

In any large company, the X5 Retail Group is no exception, as the number of projects where user authentication is required increases as the number of projects grows. Over time, a seamless transition of users from one application to another is required and then there is a need to use a single server Single-Sing-On (SSO). But what about when such identity providers as AD or others that do not have additional attributes are already used in various projects. A class of systems called “identity brokers” will come to the rescue. The most functional are its representatives, such as Keycloak, Gravitee Access management, etc. Most often, usage scenarios can be different: machine interaction, user participation, etc. The solution must support flexible and scalable functionality that can combine all requirements into one, and such a solution our company is now an indicator broker – Keycloak.

Keycloak is an open source product for authentication and access control supported by RedHat. It is the basis for company products using SSO – RH-SSO.

Basic concepts

Before you begin to deal with solutions and approaches, you should determine in terms and sequence of processes:

Identification – This is a procedure for recognizing a subject by its identifier (in other words, it is the definition of a name, login or number).

Authentication – this is an authentication procedure (the user is checked with a password, the letter is verified by electronic signature, etc.)

Login – This is providing access to some resource (for example, email).

Keycloak Identity Broker

Keycloak Is an open source identification and access management solution designed for use in ICs where microservice architecture patterns can be used.

Keycloak offers features such as single sign-on (SSO), broker identification and social login, user federation, client adapters, an admin console, and an account management console.

Basic functionality supported by Keycloak:

  • Single-Sign On and Single-Sign Out for browser-based applications.
  • Support for OpenID / OAuth 2.0 / SAML.
  • Identity Brokering – Authentication using external OpenID Connect or SAML identity providers.
  • Social Login – support for Google, GitHub, Facebook, Twitter for user identification.
  • User Federation – synchronization of users from LDAP and Active Directory servers and other identity providers.
  • Kerberos bridge – use Kerberos server for automatic user authentication.
  • Admin Console – for unified management of settings and solution parameters via the Web.
  • Account Management Console – for self-management of user profiles.
  • Customization solutions based on the corporate identity of the company.
  • 2FA Authentication – TOTP / HOTP support using Google Authenticator or FreeOTP.
  • Login Flows – self-registration of users, password recovery and reset, and others are possible.
  • Session Management – Administrators can manage user sessions from a single point.
  • Token Mappers – binding user attributes, roles and other required attributes to tokens.
  • Flexible policy management through realm, application and users.
  • CORS Support – Client adapters have built-in CORS support.
  • Service Provider Interfaces (SPI) – a large number of SPIs that allow you to configure various aspects of the server: authentication flows, identity providers, protocol mapping, and much more.
  • Client adapters for JavaScript applications, WildFly, JBoss EAP, Fuse, Tomcat, Jetty, Spring.
  • Support for working with various applications that support the OpenID Connect Relying Party library or SAML 2.0 Service Provider Library.
  • Expandability using plugins.

For CI / CD processes, as well as automation of management processes in Keycloak, the REST API / JAVA API can be used. Documentation is available in electronic form:



Enterprise Identity Providers (On-Premise)

The ability to authenticate users through User Federation services.

Pass-through authentication can also be used – if users authenticate at workstations with Kerberos (LDAP or AD), then they can be automatically authenticated with Keycloak without having to re-enter their username and password.

For authentication and further authorization of users, it is possible to use a relational DBMS, which is most applicable for development environments, since it does not entail long-term settings and integrations in the early stages of projects. By default, Keycloak uses a built-in DBMS to store settings and user data.

The list of supported DBMSs is extensive and includes: MS SQL, Oracle, PostgreSQL, MariaDB, Oracle and others. The most tested at the moment are Oracle 12C Release1 RAC and Galera 3.12 cluster for MariaDB 10.1.19.

Identity Providers – social login

It is possible to use a login from social networks. To activate the ability to authenticate users, the Keycloack admin console is used. Changes in the application code are not required and this functionality is available “out of the box” and can be activated at any stage of the project.

To authenticate users, it is possible to use OpenID / SAML Identity providers.

Typical Authorization Scenarios Using OAuth2 in Keycloak

Authorization Code Flow – used with server-side applications. One of the most common types of authorization permissions, since it is well suited for server applications in which the application source code and client data are not accessible to outsiders. The process in this case is based on redirection. The application should be able to interact with the user agent (user-agent), such as a web browser — to receive API authorization codes redirected through the user agent.

Implicit flow – used by mobile or web applications (applications running on the user’s device).

An implicit type of authorization permission is used by mobile and web applications where client privacy cannot be guaranteed. The implicit permission type also uses user agent redirection, and the access token is passed to the user agent for further use in the application. This makes the token available to the user and other applications on the user’s device. With this type of authorization permission, the application is not authenticated, and the process itself relies on the redirect URL (previously registered in the service).

Implicit Flow does not support refresh tokens.

Client Credentials Grant Flow – used when the application accesses the API. This type of authorization permission is typically used for server-to-server interactions that must run in the background without immediate user interaction. The client credential flow allows the web service (the confidential client) to use its own credentials instead of impersonating the user for authentication when calling another web service. For a higher level of security, it is possible for the calling service to use a certificate (instead of a shared secret) as credentials.

The OAuth2 specification is described in

JWT token and its advantages

JWT (JSON Web Token) – open standard (, which defines a compact and stand-alone way for the secure transmission of information between the parties in the form of a JSON object.

According to the standard, the token consists of three parts in base-64 format, separated by dots. The first part is called the header, which contains the type of token and the name of the hash algorithm for obtaining a digital signature. The second part stores the basic information (user, attributes, etc.). The third part is a digital signature.

Never save a token in your database. Because a valid token is equivalent to a password, storing a token is like storing a password in clear text.
Access token – This is a token that provides access to its owner to the protected resources of the server. Usually it has a short lifespan and can carry additional information, such as the IP address of the party requesting this token.

Refresh Token – This is a token that allows customers to request new access tokens after their lifetime. These tokens are usually issued for a long period.

Main advantages of application in microservice architecture:

  • Ability to access various applications and services through one-time authentication.
  • In the absence of a number of required attributes in the user profile, it is possible to enrich with data that can be added to the payload, including automated and on-the-fly.
  • There is no need to store information about active sessions, the server application should only verify the signature.
  • More flexible access control with additional attributes in the payload.
  • The use of a token signature for the header and payload increases the security of the solution as a whole.

JWT Token – Composition

Headline – by default, the header contains only the type of token and the algorithm used for encryption.

The type of token is stored in the “typ” key. The “typ” key is ignored in the JWT. If the typ key is present, its value must be JWT to indicate that this object is a JSON Web Token.

The second alg key defines the algorithm used to encrypt the token. By default, it should be set to HS256. The header is encoded in base64.

{“alg”: “HS256”, “typ”: “JWT”}
Payload (content) – The payload stores any information that needs to be verified. Each key in the payload is known as a “statement”. For example, the application can only be entered by invitation (closed promo). When we want to invite someone to participate, we send him an invitation letter. It is important to verify that the email address belongs to the person who accepts the invitation, so we will include this address in the payload, for this we will save it in the “e-mail” key

{“email”: “”}

The keys in payload can be arbitrary. However, there are a few reserved ones:

  • iss (Issuer) – defines the application from which the token is sent.
  • sub (Subject) – defines the topic of the token.
  • aud (Audience) – an array of case-sensitive strings or URIs, which is a list of recipients of this token. When the receiving party receives a JWT with this key, it must check for itself in the recipients – otherwise, ignore the token.
  • exp (Expiration Time) – Indicates when the token expires. The JWT standard requires expired tokens to be rejected in all its implementations. The exp key must be a timestamp in unix format.
  • nbf (Not Before) is the time in unix format that defines the moment when the token becomes valid.
  • iat (Issued At) – This key represents the time when the token was issued and can be used to determine the age of the JWT. The iat key must be a timestamp in unix format.
  • Jti (JWT ID) – a string that defines the unique identifier of this token case-sensitive.

It is important to understand that the payload is not transmitted in encrypted form (although tokens can be embedded and then it is possible to transmit encrypted data). Therefore, it is impossible to store any secret information in it. Like the header, the payload is encoded in base64.
Signature – when we have the header and payload, we can calculate the signature.

Base64 encoded: title and payload are taken, they are combined into a line through a dot. Then this line and the secret key are sent to the input of the encryption algorithm indicated in the header (key “alg”). The key can be any string. Longer strings will be preferable, as it will take more time to match.

{“alg”: “RSA1_5″, “payload”: “A128CBC-HS256”}

Keycloak Failover Cluster Architecture

When using a single cluster for all projects, there are increased requirements for a solution for SSO. When the number of projects is small, these requirements are not so noticeable for all projects, but with an increase in the number of users and integrations, the requirements for availability and productivity increase.

Increasing the risk of failure of a single SSO increases the requirements for the solution architecture and the methods used for component redundancy and leads to a very tight SLA. In this regard, more often when developing or in the early stages of implementing solutions, projects have their own non-fault-tolerant infrastructure. As you develop, you need to lay the possibility of development and scaling. The most flexible is to build a failover cluster using container virtualization or a hybrid approach.

To operate in Active / Active and Active / Passive clusters, it is required to ensure the consistency of data in a relational database – both database nodes must be synchronously replicated between different geo-distributed data centers.

The simplest example of a fail-safe installation.

What are the benefits of using a single cluster:

  • High availability and performance.
  • Support for operating modes: Active / Active, Active / Passive.
  • The ability to dynamically scale – when using container virtualization.
  • Possibility of centralized management and monitoring.
  • Unified approach for identification / authentication / authorization of users in projects.
  • More transparent interaction between various projects without user participation.
  • The ability to reuse the JWT token in various projects.
  • Single point of trust.
  • Faster launch of projects using microservices / container virtualization (no need to raise and configure additional components).
  • Perhaps the acquisition of commercial support from the vendor.

Things to consider when planning a cluster


Keycloak uses a database management system to save: realms, clients, users, etc.
A wide range of DBMSs is supported: MS SQL, Oracle, MySQL, PostgreSQL. Keycloak comes with its own built-in relational database. Use for non-loaded environments such as development environments is recommended.

To operate in Active / Active and Active / Passive clusters, it is required to ensure the consistency of data in a relational database, and both nodes of the database cluster are synchronously replicated between the data centers.

Distributed Cache (Infinspan)

For the cluster to work correctly, additional synchronization of the following cache types using JBoss Data Grid is required:

Authentication sessions – used to save data during authentication of a specific user. Requests from this cache typically include only the browser and Keycloak server, not the application.

Action tokens – used for scenarios when the user needs to confirm the action asynchronously (via email). For example, during the forget password stream, the actionTokens Infinispan cache is used to track metadata about related action markers that have already been used, so it cannot be reused.

Caching and invalidation of persistent data – used to cache persistent data to avoid unnecessary database queries. When a Keycloak server updates data, all other Keycloak servers in all data centers should be aware of this.

Work – used only for sending invalidation messages between cluster nodes and data centers.

User sessions – used to save data about user sessions that are valid during a user’s browser session. The cache must handle HTTP requests from the end user and the application.

Brute force protection – used to track failed login data.

Load balancing

The load balancer is a single entry point in keycloak and should support sticky sessions.

Application server

They are used to control the interaction of components among themselves and can be virtualized or containerized using existing automation tools and dynamically scaling infrastructure automation tools. The most common deployment scenarios in OpenShift, Kubernates, Rancher.

On this, the first part – theoretical – is over. In the following series of articles, examples of integrations with various identification providers and configuration examples will be discussed.

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *