# 企业级 AD + Keycloak + RAGFlow 完整闭环

很好，这一步就是**企业级 AD + Keycloak + RAGFlow 完整闭环**了，我给你一套可以直接落地的标准方案（生产可用）。

---

# 一、目标架构（最终形态）

```text
Windows AD (192.168.0.5)
        │ LDAP / LDAPS
        ▼
   Keycloak（身份中台）
        │ OIDC
        ▼
   RAGFlow（自动建用户 + 角色映射）

```

---

# 二、你要实现的3个能力

必须同时完成：

## ✔ 1. AD用户自动同步

## ✔ 2. 首次登录自动创建RAGFlow用户

## ✔ 3. AD Group → RAGFlow Role 映射

---

# 三、Keycloak 配置（核心）

## 1️⃣ LDAP 接入 AD

进入：

```
User Federation → LDAP

```

配置：

<table id="bkmrk-%E5%8F%82%E6%95%B0-%E5%80%BC-vendor-active-d"><thead><tr><th>参数</th><th>值</th></tr></thead><tbody><tr><td>Vendor</td><td>Active Directory</td></tr><tr><td>Connection URL</td><td>ldap://192.168.0.5:389</td></tr><tr><td>Bind DN</td><td>CN=ldapbind,OU=ServiceAccounts,DC=shuncom,DC=local</td></tr><tr><td>Bind Credential</td><td>\*\*\*\*\*\*</td></tr><tr><td>Users DN</td><td>DC=shuncom,DC=local</td></tr><tr><td>Import Users</td><td>✔ ON</td></tr><tr><td>Edit Mode</td><td>READ\_ONLY</td></tr></tbody></table>

---

# 四、关键：开启“自动用户导入”

在 LDAP 设置中：

## ✔ 必须开启：

```text
Import Users = ON

```

否则不会同步 AD 用户

---

# 五、Keycloak Role / Group 映射（关键步骤）

---

## 2️⃣ 创建 Mapper（重点）

进入：

```
LDAP → Mappers

```

新增：

---

### ✔ Mapper 1：用户名

<table id="bkmrk-name-value-ldap-attr"><thead><tr><th>Name</th><th>value</th></tr></thead><tbody><tr><td>ldap attribute</td><td>sAMAccountName</td></tr><tr><td>user attribute</td><td>username</td></tr></tbody></table>

---

### ✔ Mapper 2：邮箱

| LDAP | mail |  
| RAGFlow | email |

---

### ✔ Mapper 3：AD Group → Keycloak Group

<table id="bkmrk-mapper-type-group-ld"><thead><tr><th>Mapper Type</th><th>group-ldap-mapper</th></tr></thead><tbody><tr><td>Groups DN</td><td>OU=Groups,DC=shuncom,DC=local</td></tr><tr><td>Membership attribute</td><td>member</td></tr></tbody></table>

---

# 六、Keycloak → RAGFlow 角色映射

---

## 3️⃣ 在 Keycloak 创建 Realm Roles

例如：

- ragflow-admin
- ragflow-user
- ragflow-reader

---

## 4️⃣ Group → Role 映射

Keycloak：

```
Group → Role Mapping

```

示例：

<table id="bkmrk-ad-group-ragflow-rol"><thead><tr><th>AD Group</th><th>RAGFlow Role</th></tr></thead><tbody><tr><td>IT\_Admin</td><td>ragflow-admin</td></tr><tr><td>AI\_User</td><td>ragflow-user</td></tr></tbody></table>

---

# 七、RAGFlow 配置（关键修改）

你现在 docker-compose 需要改这几个：

---

## ✔ 1. 改用户ID来源（非常关键）

```bash
OAUTH2_USER_ID_CLAIM=email

```

❗不要用 sub

---

## ✔ 2. 开启自动注册（关键）

```bash
REGISTER_ENABLED=1

```

---

## ✔ 3. 保留 OIDC

```bash
OAUTH2_ENABLE=True
OAUTH2_TYPE=oidc

```

---

## ✔ 4. 建议补充（重要）

```bash
OAUTH2_AUTO_CREATE_USER=true

```

（如果版本支持）

---

# 八、RAGFlow 角色映射方式（核心）

RAGFlow 本身是靠 OIDC claims：

你需要在 Keycloak 加：

---

## 5️⃣ Client Mapper（重点）

进入：

```
Client → ragflow → Mappers

```

添加：

---

### ✔ Mapper 1：roles

<table id="bkmrk-name-roles-mapper-ty"><thead><tr><th>Name</th><th>roles</th></tr></thead><tbody><tr><td>Mapper Type</td><td>User Realm Role</td></tr><tr><td>Token Claim Name</td><td>roles</td></tr><tr><td>Add to ID token</td><td>ON</td></tr><tr><td>Add to access token</td><td>ON</td></tr></tbody></table>

---

### ✔ Mapper 2：groups

<table id="bkmrk-name-groups-mapper-t"><thead><tr><th>Name</th><th>groups</th></tr></thead><tbody><tr><td>Mapper Type</td><td>Group Membership</td></tr><tr><td>Token Claim</td><td>groups</td></tr></tbody></table>

---

# 九、RAGFlow 侧角色识别

RAGFlow 会读取：

```json
{
  "email": "8108@shuncom.local",
  "groups": ["AI_User"],
  "roles": ["ragflow-user"]
}

```

---

# 十、用户自动创建逻辑（关键机制）

当用户第一次登录：

```text
Keycloak 登录成功
        ↓
RAGFlow 收到 email
        ↓
检查用户是否存在
        ↓
不存在 → 自动创建
        ↓
绑定 role/group

```

---

# 十一、你必须改的最终配置（直接可用）

## docker-compose.yml（最终建议）

```yaml
environment:
  - OAUTH2_ENABLE=True
  - OAUTH2_TYPE=oidc
  - OAUTH2_DISPLAY_NAME=AD域账号登录

  - OAUTH2_AUTHORIZATION_URL=http://192.168.4.16:8081/realms/shuncom/protocol/openid-connect/auth
  - OAUTH2_TOKEN_URL=http://192.168.4.16:8081/realms/shuncom/protocol/openid-connect/token
  - OAUTH2_USERINFO_URL=http://192.168.4.16:8081/realms/shuncom/protocol/openid-connect/userinfo

  - OAUTH2_CLIENT_ID=ragflow
  - OAUTH2_CLIENT_SECRET=xxxx

  - OAUTH2_REDIRECT_URI=http://192.168.4.16/oauth/callback

  - OAUTH2_USER_ID_CLAIM=email
  - REGISTER_ENABLED=1

```

---

# 十二、最终效果（你会得到）

## ✔ AD账号登录RAGFlow

## ✔ 首次登录自动创建用户

## ✔ AD组自动映射权限

## ✔ Keycloak统一身份中心

## ✔ RAGFlow无需本地维护账号

---

# 十三、如果你要更进一步（推荐升级）

我可以帮你再升级成：

### ✔ AD组 → RAGFlow菜单权限控制

### ✔ 多租户隔离（部门级权限）

### ✔ 自动禁用离职AD用户

### ✔ LDAP双向同步

### ✔ HTTPS + 企业SSO统一入口

只需要说一句：

> “升级成企业级SSO完整方案”

我可以给你一套**生产环境标准架构（含Keycloak导入模板 + LDAP配置 + RAGFlow最终docker-compose）**。