# Keycloak — Open Source Identity & Access Management

> Keycloak is the most widely deployed open-source IAM solution. SSO, OIDC, SAML, LDAP federation, MFA, social login, and user management for enterprise applications.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name keycloak -p 8080:8080 
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin 
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin 
  quay.io/keycloak/keycloak:latest start-dev
```

Open `http://localhost:8080` — login to Admin Console and create your first realm.

## Intro

**Keycloak** is the most widely deployed open-source Identity and Access Management (IAM) solution, maintained by Red Hat. It provides single sign-on (SSO), identity brokering, user federation, and fine-grained authorization for modern applications and services — with support for standard protocols including OpenID Connect, OAuth 2.0, and SAML 2.0.

With 33.8K+ GitHub stars and Apache-2.0 license, Keycloak is the enterprise standard for self-hosted identity management, used by government agencies, financial institutions, and thousands of organizations worldwide.

## What Keycloak Does

- **Single Sign-On (SSO)**: One login for all your applications via OIDC and SAML
- **Identity Brokering**: Federate with external identity providers (Google, GitHub, Facebook, SAML IdPs)
- **User Federation**: Connect LDAP/Active Directory for centralized user management
- **Multi-Factor Auth**: TOTP, WebAuthn/FIDO2, SMS OTP, and email verification
- **User Self-Service**: Self-registration, password reset, profile management, and account linking
- **Fine-Grained Authorization**: Resource-based, role-based, and attribute-based access control
- **Admin Console**: Web-based admin UI for managing realms, clients, users, and roles
- **Account Console**: End-user portal for managing profile, sessions, and linked accounts
- **Client Adapters**: SDKs for Java, JavaScript, Node.js, Python, and more

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Applications│────▶│  Keycloak    │────▶│  PostgreSQL /│
│  (OIDC/SAML) │     │  Server      │     │  MySQL /     │
└──────────────┘     │  (Java/Quarkus)│   │  MariaDB     │
                     └──────┬───────┘     └──────────────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
       ┌──────┴──┐   ┌─────┴───┐   ┌─────┴───┐
       │  LDAP / │   │ Social  │   │ SAML    │
       │  AD     │   │ Login   │   │ IdPs    │
       └─────────┘   └─────────┘   └─────────┘
```

## Self-Hosting

### Docker Compose (Production)

```yaml
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start
    ports:
      - "8080:8080"
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_HOSTNAME: auth.yourdomain.com
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: your-admin-password
      KC_PROXY_HEADERS: xforwarded
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
      POSTGRES_DB: keycloak
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  pg-data:
```

## Core Concepts

### Realms

```
Keycloak Instance
├── Master Realm (admin only)
├── Company Realm
│   ├── Users & Groups
│   ├── Clients (Applications)
│   ├── Roles
│   ├── Identity Providers
│   └── Authentication Flows
└── Partner Realm
    ├── Users & Groups
    └── Clients
```

Each realm is an isolated identity namespace with its own users, clients, and settings.

### Client Registration

```json
{
  "clientId": "my-web-app",
  "protocol": "openid-connect",
  "rootUrl": "https://myapp.com",
  "redirectUris": ["https://myapp.com/callback"],
  "webOrigins": ["+"],
  "publicClient": true
}
```

### Integration Example (Node.js)

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

const app = express();
const keycloak = new Keycloak({}, {
  realm: 'my-realm',
  'auth-server-url': 'http://localhost:8080',
  resource: 'my-web-app',
  'public-client': true,
});

app.use(keycloak.middleware());

// Protected route
app.get('/api/data', keycloak.protect(), (req, res) => {
  res.json({ user: req.kauth.grant.access_token.content });
});

// Role-based access
app.get('/api/admin', keycloak.protect('realm:admin'), (req, res) => {
  res.json({ message: 'Admin area' });
});
```

### Custom Authentication Flows

```
Browser Login Flow:
  1. Cookie (check existing session)
  2. Identity Provider Redirector (SSO)
  3. Username/Password Form
  4. OTP Form (if MFA enabled)
  5. Conditional: WebAuthn (if passkey registered)
```

## Keycloak vs Alternatives

| Feature | Keycloak | Authentik | Zitadel | Auth0 |
|---------|----------|----------|---------|-------|
| Open Source | Yes (Apache-2.0) | Yes | Yes (AGPL) | No |
| SAML + OIDC | Both | Both | Both | Both |
| LDAP Federation | Yes (mature) | Basic | No | Enterprise |
| User Federation | LDAP, Kerberos, custom | LDAP | SCIM | Enterprise |
| Language | Java (Quarkus) | Python | Go | N/A |
| RAM usage | ~512MB-1GB | ~500MB | ~200MB | N/A |
| Maturity | 10+ years | 3 years | 4 years | 10+ years |
| Enterprise support | Red Hat SSO | Community | Cloud | Paid |

## FAQ

**Q: Is Keycloak resource-heavy?**
A: Keycloak is built on Java/Quarkus and needs at least 512 MB RAM (1–2 GB recommended). It's heavier than Go alternatives (Zitadel uses ~200 MB) but significantly leaner than the old WildFly-era versions (~2 GB).

**Q: How many users can it handle?**
A: A single instance can serve hundreds of thousands of users. For millions of users, use a clustered deployment (Keycloak supports Infinispan cluster caching). Large-enterprise deployments have been proven at tens of millions of users.

**Q: Is migrating from Auth0 to Keycloak hard?**
A: Both support the OIDC standard, so application-level migration mostly means swapping SDK configuration. User data migration can be handled via Keycloak's User Storage SPI or bulk import API. Social login configurations need to be redone.

## Sources & Credits

- GitHub: [keycloak/keycloak](https://github.com/keycloak/keycloak) — 33.8K+ ⭐ | Apache-2.0
- Website: [keycloak.org](https://keycloak.org)

---
Source: https://tokrepo.com/en/workflows/keycloak-open-source-identity-access-management-2d385875
Author: AI Open Source