# bff

**Repository Path**: gzcltech/bff

## Basic Information

- **Project Name**: bff
- **Description**: Backend for Frontend
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BFF + OAuth2 前后端分离示例

基于 **Backend for Frontend (BFF) + SSO** 架构，使用 **Spring Authorization Server** 作为授权服务器，演示完整 OAuth2 授权码流程。

## 项目结构

```
bff/
├── authorization-server/   # 授权服务器 Spring Authorization Server (:9000)
├── resource-server/        # 资源服务器，JWT 校验 (:8081)
├── bff-oauth2-server/      # BFF OAuth2 客户端 (:8080)
└── bff-oauth2-web/         # 前端 SPA Vue 3 + Vite (:5173)
```

## 架构

```
Vue SPA :5173
    │ Cookie/API
    ▼
BFF :8080  ── authorization_code ──►  Authorization Server :9000
    │ Bearer access_token
    ▼
Resource Server :8081
```

| 服务 | 端口 | 角色 |
|------|------|------|
| authorization-server | 9000 | 用户登录、签发 JWT token |
| bff-oauth2-server | 8080 | OAuth2 机密客户端，代理 API |
| resource-server | 8081 | 校验 JWT，提供业务 API |
| bff-oauth2-web | 5173 | 前端 SPA |

## 快速启动（按顺序）

### 1. 授权服务器

```bash
cd authorization-server
mvn spring-boot:run
```

- 地址：http://localhost:9000
- OIDC Discovery：http://localhost:9000/.well-known/openid-configuration
- 测试账号：`user` / `password`

### 2. 资源服务器

```bash
cd resource-server
mvn spring-boot:run
```

- 地址：http://localhost:8081
- 通过 `issuer-uri: http://localhost:9000` 自动拉取 JWK 校验 JWT

### 3. BFF

```bash
cd bff-oauth2-server
mvn spring-boot:run
```

- 地址：http://localhost:8080
- `issuer-uri` 指向授权服务器，自动发现 OIDC 端点

### 4. 前端

```bash
cd bff-oauth2-web
npm install
npm run dev
```

访问 http://localhost:5173 ，点击「SSO 登录」。

## 客户端注册（已预配置）

授权服务器 `application.yml` 中已注册 BFF 客户端，与 BFF 配置一致：

| 配置项 | 值 |
|--------|-----|
| client-id | `bff-client` |
| client-secret | `bff-client-secret` |
| redirect-uri (SPA) | `http://localhost:8080/login/oauth2/code/bff-client` |
| redirect-uri (移动端) | `myapp://oauth/callback` |
| scope | openid, profile, read, write |
| issuer | `http://localhost:9000` |

BFF 侧对应配置（`bff-oauth2-server/application.yml`）：

```yaml
spring.security.oauth2.client.registration.bff-client:
  client-id: bff-client
  client-secret: bff-client-secret
  issuer-uri: http://localhost:9000   # 通过 provider.bff-client 配置
```

> `issuer-uri` 必须与授权服务器 `spring.security.oauth2.authorizationserver.issuer` 完全一致。

## 登录流程

1. 前端跳转 `http://localhost:8080/oauth2/authorization/bff-client`
2. BFF 重定向到 `http://localhost:9000/oauth2/authorize`
3. 用户在授权服务器登录（`user` / `password`）
4. 授权服务器回调 BFF：`/login/oauth2/code/bff-client?code=xxx`
5. BFF 向 `:9000/oauth2/token` 换取 access_token，存入 Session
6. BFF 重定向前端 `/auth/callback`
7. 前端调 `/api/user/me` 获取用户信息
8. 前端调 `/api/proxy/resources`，BFF 带 Bearer token 访问 `:8081`

## 主要 API

| 服务 | 端点 | 说明 |
|------|------|------|
| 授权服务器 | `GET /.well-known/openid-configuration` | OIDC 发现 |
| 授权服务器 | `GET /oauth2/authorize` | 授权端点 |
| 授权服务器 | `POST /oauth2/token` | 换 token |
| BFF | `GET /oauth2/authorization/bff-client` | 发起 SSO |
| BFF | `GET /api/user/me` | 当前用户 |
| BFF | `GET /api/proxy/resources` | 代理资源 API |
| 资源服务器 | `GET /api/resources` | 资源列表（需 JWT） |

## 移动端

移动端通过 PKCE 从授权服务器获取 code，提交给 BFF：

```http
POST http://localhost:8080/api/auth/mobile/token
Content-Type: application/json

{
  "code": "...",
  "redirectUri": "myapp://oauth/callback",
  "codeVerifier": "..."
}
```

## 生产部署注意

1. 将 `{noop}` 前缀的 client-secret 改为 `{bcrypt}` 等安全编码
2. 授权服务器使用持久化 RegisteredClientRepository（数据库）
3. JWK 密钥持久化，避免重启后 token 失效
4. 更新所有服务中的 `localhost` 为实际域名
5. 启用 HTTPS