Keycloak

Keycloak is a server that handles user login on behalf of your applications. Instead of building a login form and password storage into every app, you hand authentication to Keycloak.

This review is for developers who want to learn how authentication works by trying it, and for administrators who want to centralize login. After reading it, you can do the following:

• Start Keycloak in development mode on your own computer
• Create a realm, a user, and a client, and sign in to a test app
• Know what to reconfigure before you use Keycloak in production

##What Keycloak is

Keycloak is open source software released under the Apache License 2.0. It is a CNCF (Cloud Native Computing Foundation) project and was accepted on April 10, 2023 at the Incubating maturity level.

##What Keycloak does

The official site lists these main features:

• Single sign-on (SSO): After one login, users can open other apps that use Keycloak without logging in again. Logout also applies to all of those apps at once.
• Standard protocols: It supports OpenID Connect, OAuth 2.0, and SAML 2.0.
• Identity brokering: You can add social login, or connect existing OpenID Connect and SAML 2.0 identity providers, from the admin console.
• User federation: It connects to existing LDAP or Active Directory servers so their users can log in.
• Admin and account consoles: Administrators manage users and applications. Users update their own profile and password and set up two-factor authentication.
• Fine-grained authorization: When roles are not enough, you can define policies to manage permissions.

For two-factor authentication, the Server Administration Guide describes one-time passwords (OTP) from an authenticator app and passkeys (WebAuthn).

##Basic terms

These definitions follow “Core concepts and terms” in the Server Administration Guide.

The built-in master realm is for managing Keycloak itself. The official guide tells you to create a separate realm for your applications.

##Trying it safely: development mode on your own computer

The official Getting started guides cover Docker and OpenJDK (unzip and run). This section follows the Docker guide. Run it only on your own computer.

1. On a computer with Docker installed, run the following command. 26.8.1 was the version when this review was written. Check the Getting started page for the current version.

   docker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:26.8.1 start-dev

   Because of 127.0.0.1, only your own computer can connect. The admin username and password are both admin. This is for practice, so do not expose it.

2. Open http://localhost:8080/admin in a browser and log in as admin.

3. In the left column, click Manage realms, then Create realm, and create a realm named myrealm.

4. Under Users, click Create new user and create myuser. Set a password under Credentials and turn Temporary off.

5. Open http://localhost:8080/realms/myrealm/account and log in as myuser. This is the Account Console for users.

6. Under Clients, click Create client. Set Client type to OpenID Connect and Client ID to myclient. Set Valid redirect URIs to https://www.keycloak.org/app/* and Web origins to https://www.keycloak.org, then save.

7. Open the official test app at https://www.keycloak.org/app/, click Save, then Sign in. If your own Keycloak login page appears, you have walked through an SSO flow.

Without Docker, follow the OpenJDK guide: unzip the distribution and run bin/kc.sh start-dev on Linux or bin\kc.bat start-dev on Windows. In that case you create the admin user the first time you open http://localhost:8080/.

##Why not to use start-dev in production

start-dev is development mode. According to the official documentation, development mode sets these defaults:

• HTTP is enabled
• Strict hostname resolution is disabled
• The cache is local to one instance (no distributed cache for high availability)
• Theme and template caching are disabled

Production mode starts with bin/kc.[sh|bat] start. It follows a “secure by default” principle: HTTP is disabled, and a hostname and HTTPS/TLS setup are expected. Without them, Keycloak shows an error on purpose and does not start.

The official documentation also warns that in development mode on Windows Subsystem for Linux (WSL), the server binds to all network addresses (0.0.0.0) by default. Other machines on your network may be able to reach it, so take care when you try it in WSL.

##What you need to run it

The full list of supported versions is on the Supported Configurations page.

##What to do in production

The official “Configuring Keycloak for production” guide covers these points:

• Use HTTPS: Keycloak exchanges sensitive data, so protect all communication with TLS.
• Set the hostname: Decide the public hostname that applications use.
• Keep the admin console off the public internet: Expose the Administration REST API and console on a different hostname or context path than the login pages. Block REST APIs that should not be public at the reverse proxy.
• Use a reverse proxy: The “Configuring a reverse proxy” guide lists which paths to expose and which to hide.
• Use a production-grade database: Configure one of the supported databases.
• Run more than one instance: A typical production setup runs two or more instances so users can still log in if one goes down.

##Following security updates

Keycloak publishes vulnerability information, with severity, in the Security Advisories of its GitHub repository. New releases are also announced in the News section of the official site. If you run Keycloak yourself, check both regularly and apply updates.

The security policy explains how to report a vulnerability. Vulnerabilities in the Keycloak codebase go to a dedicated email address, not to a public issue.

##Cautions

##Read next

• cd ../zapZAPa tool for testing your own web applications
• cd ../wazuhWazuha security platform that collects and monitors logs
• cat ~/guides/lab-setup.mdHow to build a safe lab