# pggold-iam

**Repository Path**: gold_3/pggold-iam

## Basic Information

- **Project Name**: pggold-iam
- **Description**: pggold统一认证平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pggold IAM（开发环境）

本目录是 pggold 统一登录与统一授权的开发环境实现。Keycloak 负责 OIDC
身份认证，IAM Admin 负责应用准入、角色、权限、数据范围、撤权与审计；ERP 与 Retail
后端通过同一个 Spring Boot Starter 接入，浏览器只持有各应用自己的 HttpOnly Cookie。

当前组件：

| 组件 | 地址 | 作用 |
| --- | --- | --- |
| Keycloak 26.7.3 | `http://localhost:18080` | `pggold-dev` realm、SSO、RP Logout、Back-Channel Logout |
| IAM Admin | `http://localhost:18083` | 身份绑定、应用准入、权限目录、角色、授权范围、审计 |
| IAM PostgreSQL | `localhost:15432` | Flyway 管理的授权权威数据 |
| ERP Redis | `localhost:16379` | ERP 独立 Sa-Token 会话与退出索引 |
| Retail Redis | `localhost:16380` | Retail 独立 Sa-Token 会话与退出索引 |

开发环境默认客户端为 Authorization Code + PKCE 公共客户端。共享开发和生产环境应改为
HTTPS、confidential client、独立密钥、备份和受控的 Keycloak service account。本目录的
Keycloak 管理员密码协调方式只用于本机开发。

### Keycloak 管理界面中文 / English

Keycloak 使用同级 `pgkeycloak` 的源码构建镜像。新建 `master` 的语言默认值直接在
`ApplianceBootstrap` 源码中设置为简体中文，并支持 English；`pggold-dev` 继续通过
Realm 导入文件声明相同策略。已移除每次启动调用管理 API 的语言配置辅助容器。

已有 Realm 的配置不会被重启覆盖，管理员选择的语言和既有身份均保留。
`dev-iam-check` 校验基础设施和导入配置，源码镜像验收另外验证实际 master 配置与完整登录。
先按 [源码构建说明](deploy/prod/keycloak-source/README.md) 构建镜像，再运行开发启动脚本。
开发机器可通过 `PGGOLD_KEYCLOAK_IMAGE` 指定已验收的对应架构镜像。

## 一、准备本地配置

把模板复制到只在本机保存的文件并替换全部占位值：

```bash
cp infra/.env.example /tmp/pggold-iam-dev.env
chmod 600 /tmp/pggold-iam-dev.env
export PGGOLD_IAM_ENV_FILE=/tmp/pggold-iam-dev.env
```

不要把该文件提交到任何仓库。业务进程共用其中的 `PGGOLD_IAM_INTERNAL_SECRET`，但 ERP、
Retail、Keycloak 和 IAM 数据库使用各自独立的存储与凭据。

## 二、启动身份与授权底座

```bash
./scripts/dev-iam-up
./scripts/dev-iam-check
```

`dev-iam-up` 启动 Keycloak、两套 PostgreSQL/Redis 并安装本地 Maven Starter；它不会清理
卷或业务数据库。`dev-iam-check` 只做 discovery、数据库、Redis 和端口健康检查。

启动 IAM Admin 时从本地环境文件导出变量，并显式开启开发环境的 Keycloak 状态协调：

```bash
set -a
. "$PGGOLD_IAM_ENV_FILE"
set +a
cd admin
PGGOLD_IAM_KEYCLOAK_COORDINATION_ENABLED=true \
PGGOLD_IAM_KEYCLOAK_ADMIN_USERNAME="$KEYCLOAK_ADMIN" \
PGGOLD_IAM_KEYCLOAK_ADMIN_PASSWORD="$KEYCLOAK_ADMIN_PASSWORD" \
mvn spring-boot:run
```

IAM Admin 启动后，Flyway 自动建立表并导入 ERP、Retail 权限目录。每次权限、准入或账号
状态变化都会增加授权版本、记录审计和 outbox；业务实例收到带内部密钥的幂等通知后失效
缓存。高风险写请求会在线确认用户和应用状态，IAM 不可用时返回 503。

## 三、创建和绑定开发账号

1. 在 Keycloak `pggold-dev` realm 创建开发用户并设置开发密码。
2. 记下该用户稳定的 Keycloak `sub`。不要把用户名、邮箱或显示名当绑定键。
3. 使用 IAM Admin `http://localhost:18083` 创建全局用户。
4. 分别为 `erp`、`retail` 建立 `issuer + sub -> globalUserId -> legacyUserId` 绑定。
5. 将应用 membership 设为 `ACTIVE`，授予应用角色，并按授权条目设置 `STORE` 等范围。
6. Retail 的 `legacyUserId` 还必须能映射到真实 `rt_staff` 且员工状态为 `ACTIVE`。

IAM Admin 页面只允许持有 Keycloak realm role `pggold-platform-admin` 的账号进入。业务后端
不持有 Keycloak realm 管理权限，只能通过内部读取接口解析身份和读取本应用授权快照。

## 四、启动 ERP 与 Retail

先导出同一个本地配置文件，再分别启动。数据库 URL、用户名和密码必须指向已核实的开发
库；示例没有内置任何业务数据库密码。

```bash
set -a
. "$PGGOLD_IAM_ENV_FILE"
set +a

cd ../pg-gold-backend
SPRING_PROFILES_ACTIVE=dev,dev-iam \
SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3307/test_pg_gold?...' \
SPRING_DATASOURCE_USERNAME='<dev-user>' \
SPRING_DATASOURCE_PASSWORD='<dev-password>' \
mvn spring-boot:run
```

```bash
set -a
. "$PGGOLD_IAM_ENV_FILE"
set +a

cd ../pggold-retail/backend
SPRING_PROFILES_ACTIVE=integration,dev,dev-iam \
SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:13309/test_pg_gold_retail?...' \
SPRING_DATASOURCE_USERNAME='<dev-user>' \
SPRING_DATASOURCE_PASSWORD='<dev-password>' \
mvn spring-boot:run
```

前端：

```bash
cd ../inoutweb
pnpm --filter @vben/web-antd dev:iam

cd ../pggold-retail/frontend
pnpm --filter @pggold-retail/web-antd dev:iam
```

访问 ERP `http://localhost:5666`、Retail `http://localhost:5668`。两个前端通过 `/back`
访问自己的后端。OIDC 模式不读取或保存 access token/refresh token，不调用旧密码登录，
也不发送原共享 Bearer Token。

## 五、接入契约

Java/Spring Boot 3.1 业务引入：

```xml
<dependency>
  <groupId>com.pg.gold</groupId>
  <artifactId>pggold-iam-spring-boot-starter</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>
```

每个业务是一个独立 OIDC client，并配置唯一回调地址、Cookie 名、Redis 前缀、`app-code`
和退出地址。Starter 提供：

- OIDC 登录桥接和服务端身份解析；
- `/iam/login`、`/iam/session`、`/iam/csrf`、`/iam/logout`；
- 版本化授权快照和 30 秒硬 TTL；
- `sid/sub/jti` 持久索引和签名校验后的 Back-Channel Logout；
- 内部失效通知、停用踢出、401/403/503 语义；
- 按操作读取 `permissionScopes`，避免把不同角色的权限并集与范围并集交叉扩大。

业务仍需实现自己的资格检查和资源归属判断。例如 Retail 继续校验员工在职状态，并把订单、
库存、导出、打印、附件、审批等查询和详情检查绑定到对应操作的门店范围。前端菜单只是展示，
不能替代后端接口权限和数据范围过滤。

非 Java 服务使用标准 OIDC 客户端接入认证，并调用 IAM 内部 HTTP 契约获取身份和授权；无需
复制 Java Starter。机器调用应单独使用 client credentials，不转发浏览器 Cookie、ID Token
或用户密码。

## 六、退出、停用和故障语义

- “退出本应用”只失效当前 Sa-Token 会话。
- “退出所有应用”先失效当前会话，再跳转 Keycloak RP-Initiated Logout；Keycloak 通过
  Back-Channel Logout 按 `sid/sub` 失效其他应用会话。
- IAM Admin 停用账号会可靠排队同步 Keycloak enabled 状态并注销 SSO。
- 开发环境直接在 Keycloak 停用/删除账号时，IAM 每 10 秒对账并停用 IAM 用户、增加各应用
  授权版本、发送失效通知。
- 普通读取可使用未超过硬 TTL 的快照；高风险写操作始终在线检查。过期或服务不可用时失败
  关闭，不回退旧本地权限或默认管理员。

## 七、回滚与清理

开发试点回滚以实例为单位切回原 profile，并重新登录。不要让同一入口同时接受 OIDC Cookie
和旧共享 Token。统一权限已经发生变更后，先冻结写入并对账，再决定是否切回本地权限快照。

普通停止不删除数据：

```bash
docker compose --env-file "$PGGOLD_IAM_ENV_FILE" -f infra/compose.yaml down
```

不要在日常回滚中执行 `down -v`，它会删除 Keycloak/IAM 数据与会话 Redis 卷。

更完整的业务接入步骤和验收清单见 [业务接入手册](docs/business-onboarding.md)，整体设计与
验证边界见父目录 [开发环境方案](../pggold-iam-development-design.md)。