Keycloak — Open Source Identity & Access Management

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)

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

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

Integration Example (Node.js)

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

常见问题

Q: Keycloak 资源消耗大吗？ A: Keycloak 基于 Java/Quarkus，最低需要 512MB RAM，推荐 1-2GB。比 Go 编写的替代方案（Zitadel ~200MB）重，但比旧版本（WildFly 时代 ~2GB）已经大幅优化。

Q: 可以处理多大规模的用户？ A: 单实例可以处理数十万用户。百万级用户建议使用集群部署（Keycloak 支持 Infinispan 集群缓存）。大型企业案例中已验证处理数千万用户。

Q: 从 Auth0 迁移到 Keycloak 难吗？ A: 两者都支持 OIDC 标准，应用层面的迁移主要是更换 SDK 配置。用户数据迁移可以通过 Keycloak 的 User Storage SPI 或批量导入 API 完成。社交登录配置需要重新设置。

来源与致谢

• GitHub: keycloak/keycloak — 33.8K+ ⭐ | Apache-2.0
• 官网: keycloak.org