# SSO 集成

Monetarie PIX 与外部身份提供者之间的单点登录集成，包括 Monetarie Backoffice SSO 枢纽。

## 前提条件

- 了解 JWT Token 格式和验证
- 访问身份提供者的签名密钥
- 服务间网络连接

## SSO 架构

```mermaid
graph LR
    USER[用户] --> SSO[Monetarie Backoffice<br/>SSO 枢纽]
    SSO -->|JWT token| PIX[Monetarie PIX]
    CORE[Core Banking] -->|Guardian JWT| PIX
```

## Token 类型

### Core Banking Guardian Token

| 字段 | 值 | 要求 |
|------|-----|------|
| `iss` | `"monetarie"` | 接受，无需 target_system 检查 |
| `sub` | 用户 ID | 必需 |
| `exp` | 过期时间戳 | 必需 |
| 算法 | HS256 | 使用 GUARDIAN_SECRET_KEY 签名 |

### SSO Token

| 字段 | 值 | 要求 |
|------|-----|------|
| `iss` | `"monetarie-sso"` | 必须包含 target_system |
| `target_system` | `"pix"` | SSO Token 必需 |
| `sub` | 用户 ID | 必需 |
| `exp` | 过期时间戳 | 必需 |
| 算法 | HS256 | 使用共享密钥签名 |

## JWT 密钥配置

Token 验证的密钥回退链：

```
JWT_SECRET  -->  GUARDIAN_SECRET_KEY  -->  SECRET_KEY_BASE
```

在 Kubernetes 中：

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: monetarie-shared-jwt-secret
  namespace: pix
type: Opaque
stringData:
  jwt-secret: "same-value-as-core-GUARDIAN_SECRET_KEY"
```

## 认证模块

### JWTAuth（Settlement 服务）

`Shared.Auth.JwtAuth` 验证 JWT Token：

1. 从 `pix_session` HttpOnly Cookie 提取 Token
2. 根据 JWT 密钥链验证签名
3. 检查 Token 未被列入黑名单（Redis）
4. 设置 `conn.assigns.current_user`

### SsoAuth（Settlement 服务）

`Shared.Auth.SsoAuth` 处理 SSO Token：

1. 从 `Authorization: Bearer` 头提取 Token
2. 验证 `iss` 字段：
   - `"monetarie"`（Core Guardian）：接受，跳过 target_system 检查
   - `"monetarie-sso"`：要求 `target_system: "pix"`
3. 密钥回退：JWT_SECRET -> GUARDIAN_SECRET_KEY -> SECRET_KEY_BASE

### Authenticate（Dict 服务）

`DictServiceWeb.Plugs.Authenticate` 验证 Dict 端点的 Token：

1. 检查 HttpOnly Cookie 或 Authorization 头
2. 根据 JWT 密钥链验证
3. 检查 Token 黑名单

## RBAC 与 SSO

Core Banking Guardian Token 绕过 RBAC 检查（SSO 透传）。这允许 Core Banking 在无需 PIX 特定角色分配的情况下进行 API 调用。

对于 SSO Token，RBAC 通过 `RequirePermission` 插件正常执行。

## 本地开发

```bash
# 使用 Core 的开发密钥进行跨服务测试
export JWT_SECRET="dev-only-secret-key-not-for-production"
```

## Token 黑名单

从任何认证模块注销时，Token 被加入 Redis 黑名单：

```
SET blacklist:{jti} 1 EX {remaining_ttl}
```

此检查在 `JWTAuth` 和 `Authenticate` 插件中执行。

## 预期结果

配置 SSO 后：

- Core Banking Guardian Token 被 PIX 接受，无需 target_system
- SSO Token 经过 target_system 检查验证
- JWT 密钥在 Core 和 PIX 之间共享
- Token 黑名单在所有认证模块注销时生效