快速开始

本指南聚焦“导入后怎么用”:

添加依赖
最小配置可启动
在 Controller 中完成“注入用户信息 + 权限校验”

1. 添加依赖

在 pom.xml 中引入 Starter：

<dependency>
    <groupId>com.frontleaves.phalanx.beacon.sso</groupId>
    <artifactId>bamboo-sso-sdk-springboot</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

2. 配置 `application.yml`

beacon:
  sso:
    enabled: true
    base-url: https://sso.example.com
    client-id: your-client-id
    client-secret: your-client-secret
    redirect-uri: http://localhost:8080/oauth/callback

    # 建议显式排除登录与公开接口，避免被 Filter 拦截
    exclude-urls:
      - /oauth/**
      - /api/v1/account/login/**
      - /api/v1/account/register/**
      - /api/v1/public/**

如果你要启用 gRPC（账户/用户/商户接口依赖）：

beacon:
  sso:
    grpc:
      enabled: true
      host: sso.example.com
      port: 5566
      app-access-id: app-xxx
      app-secret-key: secret-xxx

SDK 启动后会自动注册 BeaconSsoFilter、默认 Controller、@InjectData / @PermissionVerify 切面。

3. 启动应用

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

4. 在业务 Controller 中使用注解

注入用户字段 + 验权

@RestController
@RequestMapping("/api/demo")
public class DemoController {

    @GetMapping("/me")
    @PermissionVerify(value = {"profile:read"})
    public BaseResponse<Map<String, Object>> me(
            @InjectData("sub") String userId,
            @InjectData("scope") List<String> scopes) {
        return BaseResponse.success("ok", Map.of(
                "userId", userId,
                "scopes", scopes
        ));
    }
}

@InjectData("sub"): 注入当前登录用户 ID
@PermissionVerify: 校验 token 的 scope 是否包含目标权限
requireAll=true（默认）表示全量匹配；false 表示任一匹配

5. 默认路由（按源码默认值）

OAuth2 路由（默认前缀: `/oauth`）

方法	路径
GET	`/oauth/login`
GET	`/oauth/callback`
GET	`/oauth/logout`
GET	`/oauth/status`

账户路由（默认前缀: `/api/v1/account`）

方法	路径
POST	`/api/v1/account/register/email`
POST	`/api/v1/account/login/password`
POST	`/api/v1/account/password/change`
POST	`/api/v1/account/logout`

用户路由（默认前缀: `/api/v1/user`）

方法	路径
GET	`/api/v1/user/userinfo`
GET	`/api/v1/user/{userId}`

公共路由（默认前缀: `/api/v1/public`）

方法	路径
POST	`/api/v1/public/register/email/code`

6. 验证接入

启动服务后，访问以下地址测试：

GET http://localhost:8080/oauth/login（应重定向到 SSO）
GET http://localhost:8080/oauth/status（查看认证状态）
带 Authorization: Bearer <token> 访问你的业务受保护接口

下一步

配置参考 - 了解所有可配置项
认证过滤器 - 过滤器与排除路径策略
@PermissionVerify - 精准权限控制
gRPC 服务 - 启用并使用账户/用户/商户能力

快速开始

On this page