Keycloak

Overview

Keycloak is an open-source identity and access management (IAM) solution developed by Red Hat. It provides a comprehensive suite of features for securing applications and services, focusing on developers and technical buyers who require control over their authentication and authorization infrastructure. Keycloak supports standard protocols such as OpenID Connect, OAuth 2.0, and SAML 2.0, making it compatible with a wide range of applications, including web, mobile, and RESTful services Keycloak documentation.

Keycloak is best suited for organizations seeking a self-hosted, customizable IAM solution. Its open-source nature means there are no licensing fees for the software itself, although commercial support is available from Red Hat. This makes it a cost-effective option for startups and enterprises alike, provided they have the internal resources to deploy and maintain it. The platform excels in scenarios requiring single sign-on (SSO) across multiple applications, secure API access, and user federation with existing identity providers like LDAP or Active Directory.

The solution includes a Keycloak Server that manages users, roles, and access policies, alongside an Admin Console for configuration and management. For end-users, an Account Console allows them to manage their own profiles, linked accounts, and sessions. For securing microservices, Keycloak Gatekeeper acts as an authentication proxy. Its extensibility is a significant advantage, allowing developers to implement custom authentication flows, user storage providers, and event listeners using its SPI (Service Provider Interface).

While Keycloak offers significant power and flexibility, its initial setup and configuration can be complex for users unfamiliar with IAM concepts or open-source deployments. However, the official documentation and a community of active users provide resources for overcoming these challenges. Its capabilities extend to managing external identities, enabling organizations to integrate with social login providers or other identity systems, functioning as an identity broker. Compared to managed services like Azure Active Directory B2C, Keycloak provides more granular control over the deployment environment and data residency, which can be critical for compliance requirements Azure AD B2C overview.

Key features

• Single Sign-On (SSO): Enables users to log in once and access multiple applications without re-authenticating, improving user experience and reducing password fatigue.
• Identity Brokering: Allows applications to authenticate users against external identity providers such as social networks (Google, Facebook) or enterprise identity systems (LDAP, Active Directory).
• User Federation: Integrates with existing user directories, including LDAP and Active Directory, to synchronize user data and streamline identity management.
• OpenID Connect & OAuth 2.0 Support: Adheres to industry-standard protocols for authentication and authorization, ensuring interoperability with various client applications and services.
• SAML 2.0 Support: Provides compatibility with older enterprise applications and service providers that rely on the Security Assertion Markup Language.
• Admin Console: A web-based interface for managing realms, clients, users, roles, and identity providers, offering comprehensive control over the Keycloak instance.
• Account Console: A user-facing web application where users can manage their own profiles, change passwords, review security events, and manage linked accounts.
• Client Adapters: Libraries and plugins for popular programming languages and frameworks (e.g., Java, JavaScript, Node.js) that simplify the integration of Keycloak with applications.
• Customizable Themes: Allows customization of the login, registration, and account management pages to match application branding.
• Extensibility (SPI): Provides a Service Provider Interface (SPI) for developers to extend Keycloak's functionality with custom authentication flows, user storage providers, event listeners, and more.
• Multi-Factor Authentication (MFA): Supports various MFA methods to enhance account security, including OTP (One-Time Password) and WebAuthn.
• Session Management: Offers robust session management capabilities, including logout, session invalidation, and configurable session timeouts.

Pricing

Keycloak is an open-source project and is free to download and use under the Apache License 2.0. There are no direct licensing costs associated with the software itself.

Common integrations

• Spring Boot: Secure Spring Boot applications using Keycloak Spring Security Adapter Keycloak Spring Boot Adapter documentation.
• Node.js/Express: Integrate Keycloak with Node.js applications using client libraries for OpenID Connect Keycloak Node.js Adapter documentation.
• React/Angular/Vue.js: Secure single-page applications (SPAs) using Keycloak JavaScript adapter Keycloak JavaScript Adapter documentation.
• Kubernetes/OpenShift: Deploy and manage Keycloak within containerized environments. Keycloak Gatekeeper can secure services within a Kubernetes cluster Keycloak Gatekeeper documentation.
• LDAP Servers: Federate users from existing LDAP directories like OpenLDAP or Microsoft Active Directory Keycloak User Federation documentation.
• Social Identity Providers: Link user accounts with social logins such as Google, GitHub, and Facebook for simplified registration and login processes Keycloak Social Identity Providers documentation.

Alternatives

• Auth0: A commercial identity platform providing authentication, authorization, and user management as a service.
• Okta: An enterprise-grade identity cloud service offering SSO, MFA, and lifecycle management.
• Azure Active Directory B2C: Microsoft's cloud-based identity service for customer-facing applications, supporting millions of users.

Getting started

To get started with Keycloak, you typically download the server distribution and run it. The following example demonstrates how to start Keycloak using Docker, which is a common and straightforward method, and then interact with it using a minimal Node.js client.

Run Keycloak with Docker

First, pull and run the Keycloak Docker image:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin --name keycloak quay.io/keycloak/keycloak:latest start-dev

This command starts Keycloak in development mode, accessible at http://localhost:8080. You can log into the Admin Console at http://localhost:8080/admin using the username admin and password admin.

Configure a Realm and Client

1. Create a Realm: In the Admin Console, hover over "Master" in the top-left and click "Add realm". Name it my-realm.
2. Create a Client: Navigate to my-realm > Clients and click "Create client".
   • Client ID: my-app
   • Client authentication: ON
   • Authorization: OFF
   • Standard flow enabled: ON
   • Valid redirect URIs: http://localhost:3000/*
   • Web origins: http://localhost:3000
   Save the client. Go to the "Credentials" tab and note the "Client secret". You'll need this.
3. Create a User: Navigate to my-realm > Users and click "Add user". Create a user (e.g., username testuser, password password). Set their password in the "Credentials" tab, ensuring "Temporary" is OFF.

Node.js Example Client

Below is a basic Node.js Express application that uses keycloak-connect to protect a route. This example assumes you have Node.js and npm installed.

1. Initialize your project:

mkdir keycloak-node-app
cd keycloak-node-app
npm init -y
npm install express keycloak-connect session

2. Create keycloak.json: Create a file named keycloak.json in your project root with your client details:

{
  "realm": "my-realm",
  "auth-server-url": "http://localhost:8080",
  "ssl-required": "external",
  "resource": "my-app",
  "credentials": {
    "secret": "YOUR_CLIENT_SECRET" 
  },
  "confidential-port": 0
}

Replace YOUR_CLIENT_SECRET with the secret you obtained from the Keycloak Admin Console.

3. Create app.js: Create a file named app.js:

const express = require('express');
const session = require('session');
const Keycloak = require('keycloak-connect');

const app = express();
const memoryStore = new session.MemoryStore();

app.use(session({
  secret: 'some secret',
  resave: false,
  saveUninitialized: true,
  store: memoryStore
}));

const keycloak = new Keycloak({ store: memoryStore });

app.use(keycloak.middleware({
  logout: '/logout',
  admin: '/admin'
}));

app.get('/', function (req, res) {
  res.send(`
    <h1>Welcome!</h1>
    <p>This page is public.</p>
    <p><a href="/protected">Go to protected page</a></p>
    <p><a href="/logout">Logout</a></p>
  `);
});

app.get('/protected', keycloak.protect('user'), function (req, res) {
  res.send(`
    <h1>Protected Page</h1>
    <p>You are logged in as: ${req.session['keycloak-token'].content.preferred_username}</p>
    <p><a href="/">Go to public page</a></p>
    <p><a href="/logout">Logout</a></p>
  `);
});

app.listen(3000, function () {
  console.log('App listening on port 3000');
});

4. Run the application:

node app.js

Now, open your browser to http://localhost:3000. When you click "Go to protected page", you will be redirected to the Keycloak login page. After logging in with your testuser credentials, you will be redirected back to the protected page Keycloak Node.js Adapter documentation.