# hasp-auth-server

**Repository Path**: opcooc/hasp-auth-server

## Basic Information

- **Project Name**: hasp-auth-server
- **Description**: HASP Auth Server 是一个基于 Spring Authorization Server 的认证授权服务，支持标准 OAuth2 流程和 JWT 签发，用户信息、客户端信息通过外部 HTTP 服务动态获取，适用于中大型分布式系统的统一认证场景。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-04-28
- **Last Updated**: 2025-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HASP Auth Server

## 📚 目录
- [项目简介](#项目简介)
- [技术选型](#技术选型)
- [功能概览](#功能概览)
- [模块划分](#模块划分)
- [接口文档](#接口文档)
    - [授权请求 (Authorize Request)](#authorize-request)
    - [获取 Token (Get Token)](#get-token)
    - [撤销 Token (Revoke Token)](#revoke-token)
    - [设备授权请求 (Device Authorization Request)](#device-authorization-request)
    - [设备验证请求 (Device Verification Request)](#device-verification-request)
    - [Token 信息查询 (Token Introspection)](#token-introspection)
    - [获取 JWK 集合 (Get JWK Set)](#get-jwk-set)
- [外部用户服务集成说明](#外部用户服务集成说明)
- [定时轮换本地密钥文件](#定时轮换本地密钥文件)
- [部署方式](#部署方式)
- [使用示例](#使用示例)
- [注意事项](#注意事项)
- [版本信息](#版本信息)

---

## 项目简介

HASP Auth Server 是一个基于 Spring Authorization Server 的认证授权服务，支持标准 OAuth2 流程和 JWT 签发，用户信息、客户端信息通过外部 HTTP 服务动态获取，适用于中大型分布式系统的统一认证场景。
<br/>
swagger-ui: `http://127.0.0.1:9898/swagger-ui/index.html`
<br/>
授权URL: `http://127.0.0.1:9898/oauth2/authorize?response_type=code&scope=profile%20openid&client_id=demo&redirect_uri=http://127.0.0.1:9527/home&state=8a0781548e7f76ae018e94e450982413`
<br/>

#### 内存启动时的内置账户信息
| 描述                | 信息                                                                 |
|---------------------|--------------------------------------------------------------------|
| 账号   | `admin`                                                            |
| 密码   | `password`                                                         |
| client_id   | `demo`                                                             |
| client_secret   | `demo`                                                             |
| redirect_uri   | `http://127.0.0.1:9527/home` MemoryTransferClientRepository文件可更改 |
## 项目截图

<p align="center">
  <img src="./docs/images/login_password.png" alt="login_password" style="width:100%;"/>
</p>
<br/>

<p align="center">
  <img src="./docs/images/login_phone.png" alt="login_phone" style="width:100%;"/>
</p>
<br/>

<p align="center">
  <img src="./docs/images/consent.png" alt="consent" style="width:100%;"/>
</p>
<br/>

<p align="center">
  <img src="./docs/images/federated_bind.png" alt="federated_bind" style="width:100%;"/>
</p>
<br/>

<p align="center">
  <img src="./docs/images/phone_register.png" alt="phone_register" style="width:100%;"/>
</p>

---

## 技术选型

- Java 21+
- Spring Boot 3.x
- Spring Authorization Server
- Spring Security 6.x
- JWT（JSON Web Token）
- Redis
- Lombok

---

## 功能概览

- 用户认证与授权
- OAuth2 授权码模式
- JWT 生成与验证
- 支持外部用户服务集成
- Token 自动刷新机制
- 定时轮换本地密钥文件
---

## 模块划分

- 认证模块：登录、登出、刷新 Token
- 用户模块：通过外部 HTTP 获取用户信息

---

## 接口文档
## OAuth2 相关接口

---

## <a name="authorize-request"></a>授权请求 (Authorize Request)
- **URI**: `/oauth2/authorize`
- **方法**: `GET`
- **说明**: 客户端应用程序向该端点请求授权，用户通过该端点进行认证。

#### 请求参数
| 参数              | 类型   | 描述                             |
|-------------------|--------|----------------------------------|
| `response_type`   | string | 授权类型（例如 `code`）           |
| `client_id`       | string | 客户端 ID                        |
| `redirect_uri`    | string | 授权完成后重定向的 URI            |
| `scope`           | string | 请求的权限范围                    |
| `state`           | string | 防止 CSRF 攻击的随机字符串         |

#### 返回参数
- **成功时**: 重定向到 `redirect_uri`，并附带授权码 `code`。
- **失败时**: 返回错误码 `error` 和描述。

---

## <a name="device-authorization-request"></a>设备授权请求 (Device Authorization Request)
- **URI**: `/oauth2/device_authorization`
- **方法**: `POST`
- **说明**: 用于设备认证流，设备通过该端点请求一个设备授权码。

#### 请求参数
| 参数                | 类型   | 描述                             |
|---------------------|--------|----------------------------------|
| `client_id`         | string | 客户端 ID                        |
| `scope`             | string | 请求的权限范围                    |

#### 返回参数
| 参数                 | 类型   | 描述                             |
|----------------------|--------|----------------------------------|
| `device_code`        | string | 设备授权码                        |
| `user_code`          | string | 用户授权码，用于用户验证操作      |
| `verification_uri`   | string | 用户输入授权码的验证页面 URL      |
| `expires_in`         | int    | 授权码的有效期（秒）               |

---

## <a name="device-verification-request"></a>设备验证请求 (Device Verification Request)
- **URI**: `/oauth2/device_verification`
- **方法**: `GET`
- **说明**: 设备通过该端点进行验证，用户在其他设备上输入授权码。

#### 请求参数
| 参数             | 类型   | 描述                              |
|------------------|--------|-----------------------------------|
| `user_code`      | string | 用户授权码，用户在其他设备上输入   |

#### 返回参数
| 参数             | 类型   | 描述                              |
|------------------|--------|-----------------------------------|
| `device_code`    | string | 设备授权码                        |
| `status`         | string | 验证状态（例如 `pending` 或 `accepted`） |

---

## <a name="get-token"></a>获取 Token (Get Token)
- **URI**: `/oauth2/token`
- **方法**: `POST`
- **说明**: 用于请求访问令牌，通常在授权码模式、密码模式和客户端凭证模式中使用。

#### 请求参数
| 参数             | 类型   | 描述                              |
|------------------|--------|-----------------------------------|
| `grant_type`     | string | 授权类型（例如 `authorization_code`）|
| `code`           | string | 授权码（如果是授权码模式）         |
| `redirect_uri`   | string | 授权成功后重定向的 URI            |
| `client_id`      | string | 客户端 ID                        |
| `client_secret`  | string | 客户端密钥                        |

#### 返回参数
| 参数             | 类型   | 描述                              |
|------------------|--------|-----------------------------------|
| `access_token`   | string | 访问令牌                           |
| `token_type`     | string | 令牌类型（例如 `bearer`）           |
| `expires_in`     | int    | 访问令牌的有效期（秒）               |
| `refresh_token`  | string | 刷新令牌                           |

---

## <a name="get-jwk-set"></a>获取 JWK 集合 (Get JWK Set)
- **URI**: `/oauth2/jwks`
- **方法**: `GET`
- **说明**: 获取 JSON Web Key Set（JWK Set），用于验证 JWT 的签名。

#### 返回参数
| 参数            | 类型   | 描述                           |
|-----------------|--------|--------------------------------|
| `keys`          | array  | JWK 数组，每个 JWK 包含如下字段：|
| `kty`           | string | 密钥类型（例如 `RSA`）           |
| `alg`           | string | 签名算法（例如 `RS256`）         |
| `use`           | string | 密钥用途（例如 `sig`）           |
| `kid`           | string | 密钥 ID                         |
| `n`             | string | RSA 模数                         |
| `e`             | string | RSA 公钥指数                     |

---

## <a name="revoke-token"></a>撤销 Token (Revoke Token)
- **URI**: `/oauth2/revoke`
- **方法**: `POST`
- **说明**: 客户端可以通过该端点撤销一个有效的访问令牌或刷新令牌。

#### 请求参数
| 参数             | 类型   | 描述                             |
|------------------|--------|----------------------------------|
| `token`          | string | 要撤销的令牌                      |
| `token_type_hint`| string | 令牌类型提示（例如 `access_token` 或 `refresh_token`）|

#### 返回参数
- **成功时**: 返回 HTTP 状态码 200。
- **失败时**: 返回错误信息。

---

## <a name="token-introspection"></a>Token 信息查询 (Token Introspection)
- **URI**: `/oauth2/introspect`
- **方法**: `POST`
- **说明**: 用于检查访问令牌的有效性，返回令牌的详细信息。

#### 请求参数
| 参数             | 类型   | 描述                             |
|------------------|--------|----------------------------------|
| `token`          | string | 需要检查的令牌                    |
| `token_type_hint`| string | 令牌类型提示（例如 `access_token`）|

#### 返回参数
| 参数             | 类型   | 描述                             |
|------------------|--------|----------------------------------|
| `active`         | boolean| 令牌是否有效                      |
| `client_id`      | string | 客户端 ID                        |
| `scope`          | string | 令牌的权限范围                    |
| `exp`            | int    | 令牌的过期时间（Unix 时间戳）      |
| `iat`            | int    | 令牌的签发时间（Unix 时间戳）      |

---

## 外部用户服务集成说明

本项目使用了 **[JustAuth](https://github.com/JustAuth/JustAuth)**，一个开源的第三方授权认证库，来实现多种平台的联合登录功能。JustAuth 提供了一种简便的方式，通过统一的接口支持多种第三方平台的 OAuth2.0 授权登录，包括但不限于：

- **微信**
- **微博**
- **QQ**
- **GitHub**
- **Google**
- **Facebook**
- **Twitter**
- **Gitee**

### 为什么使用 JustAuth？
JustAuth 简化了不同平台 OAuth2.0 登录的集成过程，它提供了：
- 一致的接口，使得在多个平台间切换更加轻松。
- 开放源代码和高度可定制的功能，能够根据需求修改和扩展。
- 完整的 OAuth2.0 支持，确保认证流程的安全和规范。
- 集成多个主流社交平台，避免了单独实现每个平台授权的繁琐过程。

通过使用 JustAuth，项目能够轻松集成并扩展不同的登录方式，使用户可以选择多种方式进行快速登录，提升了用户体验。

### 如何集成 JustAuth
JustAuth 通过其统一的 API 进行认证授权，在本项目中已经实现了基本的集成。以下是配置和使用的一些关键步骤：

1. **配置授权平台**
   在 application.yml 文件中配置各平台的 API 密钥和回调地址。

   ```
   justauth:
      oauth2:
        WECHAT_OPEN:
          client-id: your-client-id
          client-secret: your-client-secret
          redirect-uri: http://127.0.0.1:9898/oauth2/federated/callback/wechat_open
        GITEE:
          client-id: your-client-id
          client-secret: your-client-secret
          redirect-uri: http://127.0.0.1:9898/oauth2/federated/callback/gitee
        GITHUB:
          client-id: your-client-id
          client-secret: your-client-secret
          redirect-uri: http://127.0.0.1:9898/oauth2/federated/callback/github

   ```

## 定时轮换本地密钥文件

1. **密钥生成与保存**：
  - 使用 `KidGenerator` 生成 `kid`，并保存公私钥到 `.pem` 文件。
  - 将当前 `kid` 存储在 `current_kid.txt`，并更新软链接 `current_private.pem` 和 `current_public.pem`。

2. **公私钥加载**：
  - 使用 `loadPublicKey` 加载公钥文件，生成 `PublicKey` 对象。
  - 使用 `loadPrivateKey` 加载私钥文件，生成 `PrivateKey` 对象。
3. **定时更新密钥文件**：
  - 使用定时任务定时生成并更新软链接 `current_private.pem` 和 `current_public.pem`。