SDK 集成（Java）

Passport SDK 基于 Cookie 共享机制实现，受跨域限制，因此主要适用于为同域站点提供认证鉴权。其意义主要在于简化应用后台认证鉴权流程的实现，只需要引入依赖包就可以一步到位完成接口拦截。

Passport SDK 当前提供 Java 和 Go 版本：

• Java SDK：适用于 Spring Boot 框架的应用
• Go SDK：适用于 Gin 框架的应用

工作原理

SDK 通过以下机制实现认证鉴权：

1. 认证拦截：通过 AuthFilter 拦截所有请求，验证 Token 有效性
2. Token 验证：使用公钥验证 JWT Token 签名，解析用户信息
3. 权限控制：从本地缓存的 API 和权限配置中，验证用户是否有访问权限
4. 缓存同步：通过定时任务从 Passport 服务同步 API 和权限配置

Step 1：引入 Maven 依赖

<dependency>
    <groupId>com.vancone</groupId>
    <artifactId>vancone-passport-sdk</artifactId>
    <version>0.1.4</version>
</dependency>

依赖说明

SDK 依赖以下组件：

• Spring Boot Starter Web - Web 应用基础
• Spring Boot Starter AOP - 面向切面编程支持
• JJWT - JWT Token 解析
• Spring Security Crypto - 加解密支持
• vancone-web-common - VanCone Web 通用组件

SDK 不需要 Redis。API 与权限配置缓存在应用进程的内存中，由定时任务刷新，接入方无需额外准备缓存中间件。

Step 2：修改配置文件

# ====================================
# Passport SDK 配置
# ====================================

# Passport 平台部署的地址，用于登录跳转和同步鉴权信息
passport.base-url=https://passport.vancone.com

# 应用账号的 Access Key ID（在 Passport 管理后台创建应用时生成）
passport.app-account.access-key-id=AKIDxxxxxxxxxxxxxxxxxx

# 应用账号的 Secret Access Key
passport.app-account.secret-access-key=xxxxxxxxxxxxxxxxxx

# Token 验证所需的公钥（Base64 编码）
passport.token.public-key=MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXxxxxxxxxxxxxxxxxxx

# Token 算法类型，当前仅支持 ES256
passport.token.algorithm=ES256

# 是否启用权限控制，false 表示只进行认证不进行鉴权
passport.access-control.enabled=true

# 本地缓存同步周期（秒），用于从 Passport 服务同步 API 和权限配置
passport.cache.sync-period-seconds=60

# 不需要认证的 URI 前缀列表（逗号分隔），如公开接口、健康检查等
passport.permitUriPrefix=/public,/health,/actuator

配置说明

Step 3：设置启动类的组件扫描范围

@SpringBootApplication
@ComponentScan(basePackages = "com.vancone")
public class PassportClientApplication {
    public static void main(String[] args) {
        SpringApplication.run(PassportClientApplication.class, args);
    }
}

注意：SDK 使用 Spring Boot 的自动配置机制，通过 spring.factories 自动注册组件。但需要确保 com.vancone 包在组件扫描范围内，否则无法加载 SDK 的 Bean。

在代码中获取当前用户信息

SDK 将解析后的用户信息存储在 ThreadLocal 中，可以在业务代码中通过 TokenUtil 获取：

import com.vancone.passport.sdk.util.TokenUtil;
import com.vancone.passport.sdk.entity.AccountInfo;

public class MyController {

    @GetMapping("/api/user/info")
    public Response getUserInfo() {
        // 获取当前登录用户的账户信息
        AccountInfo accountInfo = TokenUtil.getAccountInfo();

        if (accountInfo != null) {
            // 获取用户 ID
            String userId = accountInfo.getUserId();

            // 获取账户 ID
            String accountId = accountInfo.getId();

            // 获取租户 ID
            String tenantId = accountInfo.getTenantId();

            // 获取权限 ID 列表
            List<Long> permissionIds = accountInfo.getPermissionIds();

            return Response.success(accountInfo);
        }
        return Response.fail(401, "Not logged in");
    }
}

AccountInfo 属性

认证流程说明

1. 请求到达：客户端发起请求，SDK 的 AuthFilter 拦截请求

2. Token 获取：SDK 按以下顺序获取 Token：

   • 从 HTTP Header passport-token 获取
   • 从 Cookie passport_token 获取

3. Token 验证：使用配置的公钥验证 Token 签名

4. 权限验证（如果启用）：

   • 从 Token 中提取用户的权限 ID 列表
   • 从本地缓存中匹配请求的 API
   • 验证用户权限是否包含该 API

5. 请求处理：验证通过后，将用户信息存入 ThreadLocal，继续处理请求

6. 清理：请求结束后，自动清理 ThreadLocal 中的用户信息

响应状态码

SDK 在认证鉴权失败时返回以下状态码：

前端可以检查 401 响应中的 data 字段，获取登录地址进行跳转。

获取公钥

管理后台当前不提供公钥查询页面。 公钥需要从 Passport 服务端的配置文件（passport.token.public-key）中获取，请向 Passport 的部署运维人员索取。

公钥为 Base64 编码的 PKIX 公钥（与私钥 passport.token.private-key 成对生成，服务端使用 ES256 签名）。

如果需要自行生成密钥对，可使用 OpenSSL：

# 生成 ES256（prime256v1）密钥对
openssl ecparam -genkey -name prime256v1 -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem

# 提取 PKIX 公钥的 Base64 正文（去掉头尾与换行）
grep -v "^-" public.pem | tr -d '\n'

将上一步输出的 Base64 字符串填入 passport.token.public-key。

服务端的 public-key 与 private-key 必须成对替换，否则已签发的 Token 将全部校验失败。

缓存同步机制

SDK 通过 SyncScheduler 定时从 Passport 服务同步数据，缓存在应用进程内存中（不依赖 Redis 等外部缓存）：

同步周期由 passport.cache.sync-period-seconds 配置控制，默认 60 秒。

创建应用账号

在 Passport 管理后台创建应用账号，获取 Access Key：

1. 登录 Passport 管理后台
2. 进入「应用管理」
3. 创建新应用或选择现有应用
4. 查看应用的 Access Key ID 和 Secret Access Key

常见问题

Q: Token 从哪里获取？

A: 用户在 Passport 平台登录后，Token 会以以下方式存储：

• Cookie：passport_token
• Header：passport-token

前端可以将 Token 设置到后续请求的 Header 中，也可以依赖 Cookie 自动传递。

Q: 如何调试 Token 验证问题？

A: SDK 会输出详细日志，可以通过以下方式调试：

# 启用 SDK 日志
logging.level.com.vancone.passport.sdk=DEBUG

Q: 支持哪些加密算法？

A: 仅支持 ES256（ECDSA using P-256 curve）。Passport 服务端签发 Token 时固定使用 ES256，passport.token.algorithm 配置仅用于校验端保持一致，填写其他算法会导致所有 Token 校验失败。