bash

下载最新版 Keycloak（以 23.0.7 为例，请访问官网获取实际链接）

wget https://github.com/keycloak/keycloak/releases/download/23.0.7/keycloak-23.0.7.zip unzip keycloak-23.0.7.zip cd keycloak-23.0.7

启动开发模式（仅限本地开发，无需数据库配置）

bin/kc.sh start-dev

默认会创建 H2 内存数据库，管理员账户需要在首次访问时设置。

### 访问管理控制台
打开浏览器访问 `http://localhost:8080`（或启动日志中的地址），点击 **Administration Console**，创建初始管理员账号并登录。

## 创建和管理 Realm
1. 登录控制台后，左侧导航栏悬停在 Master realm 上，点击 **Add realm**。
2. 输入 realm 名称（如 `myapp-realm`），支持中文命名。
3. 点击 **Create**。

新创建的 realm 将拥有完全独立的用户、角色和客户端配置。

## 定义客户端
客户端代表需要 Keycloak 保护的应用。

### 创建 OpenID Connect 客户端
1. 进入目标 realm，左侧菜单选择 **Clients**，点击 **Create client**。
2. **Client type** 选择 `OpenID Connect`。
3. 输入 **Client ID**（如 `frontend-web`），名称仅作为标识。
4. 点击 **Next**。
5. 保持标准流程选项开启，并务必启用 **Client authentication** 中的*Client Id and Secret*（对于后端服务）或根据需要选择 *Public access*（对于纯前端 SPA）。
6. 后续设置 **Valid redirect URIs**，例如 `http://localhost:3000/*`（允许前端回调）。
7. 保存配置。

创建后，在客户端的 **Credentials** 标签页可获得客户端密钥（对于机密客户端），用于后端验证。

## 管理用户与角色
### 添加用户
进入 **Users** → **Add user**，填写用户名，可设置邮箱、姓名等，创建后可在 **Credentials** 标签页设置初始密码，并可选择临时密码（用户首次登录需修改）。

### 创建角色
- **Realm roles**：全局角色，可跨客户端复用。
- **Client roles**：绑定在某个客户端下的细粒度角色。

进入 **Realm roles**，点击 **Create role**，输入角色名称（如 `admin`、`user`）后保存。
在用户详情页的 **Role mapping** 中分配角色。

## 使用 Keycloak 保护你的第一个应用
以下以 Node.js 后端为例，展示如何集成 Keycloak。

### 步骤 1：获取客户端凭证
在 Keycloak 中进入对应客户端，获取：
- **Auth Server URL**：`http://localhost:8080`（你的 Keycloak 地址）
- **Realm name**：`myapp-realm`
- **Client ID**：`frontend-web`
- **Client Secret**（仅机密客户端需要）

### 步骤 2：安装适配器
```bash
npm install keycloak-connect express-session express

步骤 3：编写服务器代码

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

const app = express();

// 配置 session
app.use(session({
  secret: 'some secret',
  resave: false,
  saveUninitialized: true,
  store: new session.MemoryStore()
}));

const keycloak = new Keycloak({}, {
  realm: 'myapp-realm',
  'auth-server-url': 'http://localhost:8080',
  'ssl-required': 'external',
  resource: 'frontend-web',   // Client ID
  'confidential-port': 0,
  credentials: {
    secret: 'your-client-secret'
  }
});

app.use(keycloak.middleware());

// 受保护的路由
app.get('/protected', keycloak.protect(), (req, res) => {
  res.json({ message: '你已通过认证！', user: req.kauth.grant.access_token.content });
});

// 根据角色保护路由
app.get('/admin', keycloak.protect('realm:admin'), (req, res) => {
  res.json({ message: '管理员页面' });
});

app.listen(3000, () => console.log('Server started on port 3000'));