# oidc

**Repository Path**: jmash/oidc

## Basic Information

- **Project Name**: oidc
- **Description**: Open ID Connect 实践
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-11-23
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jmash-oidc 项目说明

## 1. 项目简介

`jmash-oidc` 是基于 Jmash 技术框架实现的 OpenID Connect（OIDC）1.0 标准实现，同时兼容 OAuth 2.0 授权框架，用于满足单点登录（SSO）场景需求。

与 Jmash 标准「模块框架」（协议库 lib → 服务 service → 网关 gateway 三段式）不同，本项目采用 **Jmash MVC 框架**构建，是单体 Web 应用（WAR 包），基于 JAX-RS + Jakarta MVC + FreeMarker 提供 OAuth/OIDC 认证授权服务及页面。

## 2. 技术栈

| 类别 | 技术 |
|---|---|
| 语言/运行时 | Java 17，Tomcat 11 + JDK 21（容器内） |
| Web 框架 | JAX-RS + Jakarta MVC + FreeMarker |
| 安全框架 | Apache Shiro（jakarta 版）+ RBAC |
| 令牌 | MicroProfile JWT（smallrye-jwt） |
| 缓存 | Redis（Jedis） |
| 数据库 | MariaDB |
| 构建 | Maven |

## 3. 目录结构

```
jmash-oidc/
├── docs/                              # 文档
│   ├── database/                      # 数据库脚本与模型
│   └── 标准规范/                       # RFC 规范
├── examples/
│   └── jmash-oidc-client-web/         # OIDC 客户端示例（Web）
├── jmash-oidc-web/                    # OIDC 服务端（核心应用，WAR）
├── jmash-oidc-k8s/                    # K8S 部署编排与 Dockerfile
└── README.md
```

核心包结构（`jmash-oidc-web`）：

```
com.gitee.jmash.oidc
├── web/                               # 登录、登出、默认页等 MVC 控制器
├── oauth2/
│   ├── jaxrs/                         # /authorize、/token、/userinfo 端点
│   ├── controller/                    # 授权页、回调页
│   ├── impl/                          # 各授权类型实现
│   ├── models/                        # 请求/响应模型
│   └── enums/                         # GrantType、ResponseType、ScopeType
```

## 4. 协议能力

### 4.1 端点

应用根路径（JAX-RS ApplicationPath）为 `/oauth`，主要端点：

| 端点 | 说明 |
|---|---|
| `/oauth/authorize` | 授权端点（GET） |
| `/oauth/token` | 令牌端点（POST） |
| `/oauth/userinfo` | 用户信息端点（GET/POST） |
| `/oauth/login` | 登录页/登录（GET/POST） |
| `/oauth/logout` | 登出（GET） |
| `/oauth/private/authorize` | 授权页（需登录） |
| `/oauth/callback` | 回调页 |

### 4.2 授权类型（Grant Type）

| 授权类型 | 支持情况 |
|---|---|
| `authorization_code` | 支持 |
| `implicit` | 支持 |
| `password` | 支持 |
| `refresh_token` | 支持 |
| `client_credentials` | 支持 |
| `urn:ietf:params:oauth:grant-type:jwt-bearer` | 预留 |

### 4.3 response_type

| response_type | 说明 |
|---|---|
| `code` | 授权码模式 |
| `id_token` | 隐式 |
| `id_token token` | 隐式 |
| `code id_token` | 混合模式 |

### 4.4 Scope

`openid`、`profile`、`email`、`phone`、`address`。

## 5. 核心配置

配置文件：`jmash-oidc-web/src/main/resources/META-INF/microprofile-config.properties`。

| 配置项 | 说明 |
|---|---|
| `jmash.web.context` | Web 上下文路径，默认 `/oidc` |
| `jmash.web.port` | Web 端口，默认 `8081` |
| `jmash.server.port` | gRPC 端口，默认 `50051` |
| `smallrye.jwt.sign.key` | JWT 签名私钥 |
| `smallrye.jwt.encrypt.key` | JWT 加密公钥 |
| `mp.jwt.verify.publickey` | JWT 验签公钥 |
| `smallrye.jwt.decrypt.key` | JWT 解密私钥 |
| `jmash.oauth.sm4key` | 授权页 `key` 参数 SM4 密钥 |
| `write.jdbc.*` / `read.jdbc.*` | 读写数据库连接 |
| `jedis.*` | Redis 连接 |

## 6. 构建与部署

部署命令与 Jmash 框架保持一致（Jmash 框架位置：`/data/work/jmash`）。

### 6.1 环境准备

前置依赖：Maven 3.6+、OpenJDK 17、Docker、可用的 K8S 集群。详见 Jmash 文档：

- 环境准备：`https://gitee.com/jmash/docs/getting-started/01-环境准备.md`
- 最小化部署：`https://gitee.com/jmash/docs/getting-started/03-最小化部署K8S.md`
- 容器化部署：`https://gitee.com/jmash/docs/operations/01-容器化部署.md`

### 6.2 部署步骤

进入 `jmash-oidc-k8s` 目录，设置 `PYTHONPATH` 指向 Jmash 命令库：

```bash
cd jmash-oidc/jmash-oidc-k8s
export PYTHONPATH=/data/work/jmash/python/jmash-cmd

# 1) 打包：Maven 构建 WAR
python3 cmd0.py package amd64

# 2) 发布：构建并推送 Docker 镜像
python3 cmd0.py publish amd64

# 3) 部署到 K8S
python3 cmd0.py deploy amd64

# 一键执行 package + publish + deploy
python3 cmd0.py all amd64
```

`cmd0.py` 支持的操作与 Jmash 一致：

| action | 说明 |
|---|---|
| `package` | Maven 构建 WAR |
| `publish` | 构建并推送 Docker 镜像 |
| `deploy` | 部署到 K8S |
| `restart` | 重启 K8S 应用 |
| `delete` | 删除 K8S 应用 |
| `scale` | 设置副本数 |
| `test` / `notest` | 开启/停止本地测试服务 |
| `all` | 一次性执行 package + publish + deploy |

常用可选参数：`--namespace`（默认 `jmash`）、`--name`（默认 `oidc`）、`--version`（默认 `1.0.0`）、`--replicas`（默认 `1`）。

### 6.3 本地运行

```bash
cd jmash-oidc/jmash-oidc-web
mvn clean package
# 生成 target/jmash-oidc-web-<version>.war，可部署到 Tomcat
```

或在 IDE 中运行启动类 `com.gitee.jmash.oidc.web.App`。

### 6.4 验证

```bash
# 查看 Pod 状态
kubectl get pods -n jmash

# 查看服务日志
kubectl logs -f jmash-oidc-service-deploy-<pod-id> -n jmash
```

## 7. 与模块框架的区别

| 维度 | 模块框架（如 jmash-dict） | jmash-oidc（本框架） |
|---|---|---|
| 架构 | lib + service + gateway 三段式 | 单体 Web 应用（WAR） |
| 界面 | 前后端分离（Vue） | 服务端渲染（FreeMarker） |
| 入口 | gRPC + Go 网关 | JAX-RS / Jakarta MVC |
| 部署产物 | JAR + 网关可执行文件 | WAR |
| 部署命令 | `cmd0.py package/publish/deploy` | 相同 |

## 8. 相关文档

- Jmash 框架：`https://gitee.com/jmash`
- Jmash 部署文档：`https://gitee.com/jmash/docs/`
- OIDC 数据库脚本：`jmash-oidc/docs/database/mysql/jmash-oidc-mysql.sql`
- 标准规范：`jmash-oidc/docs/标准规范/rfc6749_The_OAuth_2.0_Authorization_Framework.pdf`