Keycloak 身份与访问管理（IAM）¶

一句话概述：Keycloak 是 Red Hat 开源的企业级身份管理系统，提供 SSO、用户管理、OAuth2/OIDC/SAML 认证协议支持，一套系统管理所有应用的登录和权限。

核心知识点¶

概念	白话解释
IAM	身份与访问管理，管"谁能访问什么"
Realm	领域，一个独立的认证空间（类似租户）
Client	需要认证的应用（你的 Web 应用、API）
OAuth 2.0 / OIDC	行业标准的授权/认证协议
SAML	另一种企业常用的 SSO 协议
User Federation	用户联邦，对接 LDAP/AD 等现有用户目录
Social Login	社交登录，Google/GitHub/微信登录

安装配置¶

Docker 快速启动¶

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  # 开发模式启动

# 访问 http://localhost:8080
# 管理控制台：http://localhost:8080/admin
# 账号密码：admin / admin

Docker Compose（带数据库）¶

version: "3"
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    command: start-dev
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

基本使用¶

配置流程¶

1. 创建 Realm（领域）
   Admin Console → Create Realm → 命名为 "my-app"

2. 创建 Client（应用）
   Clients → Create → 
   - Client ID: my-web-app
   - Client Type: OpenID Connect
   - Root URL: http://localhost:3000
   - Valid Redirect URIs: http://localhost:3000/*

3. 创建用户
   Users → Create →
   - Username: zhangsan
   - Email: zhang@example.com
   - 设置密码（Credentials 标签页）

4. 获取配置信息
   Clients → my-web-app → Keys
   记录 Client Secret

   Realm Settings → Endpoints → OpenID Endpoint Configuration
   获取各种 endpoint URL

前端集成（React）¶

npm install keycloak-js  # 安装 Keycloak JS 适配器

// src/keycloak.ts
import Keycloak from 'keycloak-js'

const keycloak = new Keycloak({
  url: 'http://localhost:8080',  // Keycloak 地址
  realm: 'my-app',  // Realm 名
  clientId: 'my-web-app',  // Client ID
})

export default keycloak

// src/App.tsx
import keycloak from './keycloak'
import { useEffect, useState } from 'react'

function App() {
  const [authenticated, setAuthenticated] = useState(false)

  useEffect(() => {
    keycloak.init({ onLoad: 'login-required' })  // 要求登录
      .then((auth) => setAuthenticated(auth))
  }, [])

  if (!authenticated) return <div>加载中...</div>

  return (
    <div>
      <p>欢迎, {keycloak.tokenParsed?.preferred_username}</p>
      <button onClick={() => keycloak.logout()}>退出</button>
    </div>
  )
}

常见报错¶

报错信息	原因	解决方案
`Invalid redirect_uri`	重定向 URL 不在白名单	在 Client 配置中添加 Valid Redirect URIs
`CORS error`	跨域问题	在 Client 的 Web Origins 加 `*` 或具体域名
`Token expired`	Token 过期	配置自动刷新 Token
管理控制台打不开	端口被占	检查 8080 端口

速查表¶

# 核心概念
Realm    = 认证空间（租户）
Client   = 需要认证的应用
User     = 用户
Role     = 角色
Group    = 用户组
Protocol = OAuth2 / OIDC / SAML

# 常用 OIDC 端点
/realms/{realm}/.well-known/openid-configuration  # 配置发现
/realms/{realm}/protocol/openid-connect/token      # 获取 Token
/realms/{realm}/protocol/openid-connect/auth       # 授权
/realms/{realm}/protocol/openid-connect/logout     # 登出
/realms/{realm}/protocol/openid-connect/userinfo   # 用户信息

参考：Keycloak 官网 | Keycloak 文档 | GitHub