Starter 使用指南

能力边界

Starter 是业务应用的接入包，不是授权服务器运行时。租户、用户、Client、MFA、JWK 和身份源仍由 ArmorAuth 服务端和管理台维护。

添加依赖

只在需要接入 ArmorAuth 的业务服务中添加 Starter。授权服务器自身不需要通过 Starter 启动。

<dependency>
  <groupId>com.armorauth</groupId>
  <artifactId>armorauth-spring-boot-starter</artifactId>
  <version>1.0.0</version>
</dependency>

OAuth2 接入方式

先在管理台创建应用，再把端点和 Client 配置写入业务服务。不同类型的业务系统不要共用同一个 Client。

Resource Server

API 服务推荐只配置资源服务器。资源服务器通过 issuer 或 JWKS 验证访问令牌，再用 Scope、角色或权限做业务授权。

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:9000

armorauth:
  resource-server:
    enabled: true

OIDC Login

传统 Web 服务或 BFF 可以作为 OAuth2 Client，通过 ArmorAuth 托管登录页完成认证，再在服务端维护会话。

spring:
  security:
    oauth2:
      client:
        registration:
          armorauth:
            client-id: dashboard
            client-secret: ${ARMORAUTH_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            client-authentication-method: client_secret_basic
            scope: openid,profile,email
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          armorauth:
            issuer-uri: http://localhost:9000

登录后身份

• 业务页面读取 OidcUser 或 OAuth2AuthenticationToken。
• 如果需要调用下游 API，优先使用 OAuth2 Authorized Client 管理访问令牌。
• 退出流程以 Discovery 或管理台端点详情为准，post logout redirect URI 必须在应用中登记。

当前用户上下文

业务服务通常需要把 JWT 或 OIDC 用户信息转换成自己的当前用户模型。推荐把 claim 映射集中封装，避免控制器重复解析 Token。

record CurrentUser(
    String subject,
    String username,
    String tenantId,
    List<String> roles,
    List<String> scopes
) {}

Admin API Client

内部自动化、批量开通和运维工具可以调用 ArmorAuth 管理 API。生产环境建议用独立服务账号、最小 Scope、超时、重试和错误映射。

RestClient adminClient = RestClient.builder()
    .baseUrl("http://localhost:9000")
    .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + adminToken)
    .build();

• 不要把超级管理员密码写入业务服务配置。
• Client Credentials 或服务账号 Token 应只授予需要的管理 Scope。
• 批量任务要记录请求 ID、调用人、租户和失败原因，便于审计。

Token Relay

Token Relay 适合 BFF 或网关把当前用户访问令牌转发给受信下游。它不等同于 OAuth2 Client 自动换取 Token， 也不应把用户 Token 发给第三方或未登记服务。

RestClient downstream = RestClient.builder()
    .baseUrl("http://orders-service")
    .requestInterceptor((request, body, execution) -> {
      Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
      if (authentication instanceof JwtAuthenticationToken jwt) {
        request.getHeaders().setBearerAuth(jwt.getToken().getTokenValue());
      }
      return execution.execute(request, body);
    })
    .build();

扩展点

业务项目的安全边界往往不同，以下能力建议作为应用内配置或后续 starter 扩展点沉淀。