💃🏽 ❔ 🎰 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,able to combine all the requirements in one, and such a solution in our company now is an indicator broker - Keycloak.

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

Basic concepts

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

Identification is the process of recognizing a subject by its identifier (in other words, it is determining a name, login or number).

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

Authorization is the provision of access to some resource (for example, email).

Keycloak Identity Broker

Keycloak is an open source identity 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 administrator console, and an account management console.

Basic functionality supported in 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 – LDAP Active Directory .
Kerberos bridge – Kerberos .
Admin Console — Web.
Account Management Console – .
.
2FA Authentication – TOTP/HOTP Google Authenticator FreeOTP.
Login Flows – , .
Session Management – .
Token Mappers – , .
realm, application .
CORS Support – CORS.
Service Provider Interfaces (SPI) – SPI, : , , .
JavaScript applications, WildFly, JBoss EAP, Fuse, Tomcat, Jetty, Spring.
, OpenID Connect Relying Party library SAML 2.0 Service Provider Library.
plugins.

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

REST API https://www.keycloak.org/docs-api/8.0/rest-api/index.html
JAVA API https://www.keycloak.org/docs-api/8.0/javadocs /index.html

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 a 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
RFC-6749
RFC-8252
RFC-6819

JWT token and its advantages

JWT (JSON Web Token) is an open standard ( https://tools.ietf.org/html/rfc7519 ) that defines a compact and standalone method for securely transferring information between parties as 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.

<encoded header>. <encoded payload>. <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.
An access token is a token that gives its owner access 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.

A refresh token is a token that allows clients to request new access tokens after their lifetime has expired. These tokens are usually issued for a long period.

Main advantages of application in microservice architecture:

The 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.
Using a token signature for the header and payload increases the security of the solution as a whole.

JWT Token - Composition

Header - 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": "example@x5.ru"}
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) – URI, . JWT , — .
exp (Expiration Time) — , . JWT , . Exp unix .
nbf (Not Before) — unix , , .
iat (Issued At) — , JWT. iat unix .
Jti (JWT ID) — , c .

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 a header and payload, we can calculate the signature.

Base64 encoded: header 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 specified 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 accessibility 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 work 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

DBMS

Keycloak uses a DBMS 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 to send invalidation messages between cluster nodes and data centers.

User sessions - used to save data about user sessions that are valid for a user's browser session. The cache must handle HTTP requests from the end user and 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, Kubernetes, 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.

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