认证开发细节

开发者架构说明

认证架构

Polaris 使用 Quarkus Security 将认证划分为两个逻辑阶段：

1. 凭据提取——解析请求头和令牌
2. 凭据认证——校验身份并分配角色

关键接口

• Authenticator：用于认证凭据并解析主体（principal）及其角色的核心接口。角色可来自 OIDC 声明或内部映射。
• InternalPolarisToken：用于内部认证，继承自 PrincipalCredential。
• DefaultAuthenticator 基于上述抽象实现 realm 特定的逻辑。

令牌代理配置

启用内部认证时，Polaris 使用 TokenBroker 来解码和校验认证令牌。这些 broker 属于请求作用域，可按 realm 进行配置。每个 realm 可根据安全需求采用各自的策略，例如 RSA 密钥对或共享密钥。配置详情参见 令牌代理说明。

开发者认证工作流

内部认证

1. InternalAuthenticationMechanism 解析认证请求头。
2. 使用 TokenBroker 解码令牌。
3. 构建 InternalAuthenticationRequest 并生成 SecurityIdentity（Quarkus）。
4. Authenticator.authenticate() 校验凭据，解析主体及其角色，随后创建 PolarisPrincipal。

外部认证

1. OidcAuthenticationMechanism（Quarkus）处理认证请求头。
2. OidcTenantResolvingAugmentor 选择 OIDC 租户。
3. OidcPolarisCredentialAugmentor 提取 JWT claims。
4. Authenticator.authenticate() 校验 claims、解析主体及其主体角色，然后创建 PolarisPrincipal。

混合认证

1. InternalAuthenticationMechanism 尝试进行解码。
2. 若成功，则继续进行内部认证。
3. 否则，回退到外部（OIDC）认证。

OIDC 配置参考

主体映射

• 接口：PrincipalMapper

  PrincipalMapper 负责从 OIDC 令牌中提取 Polaris 主体 ID 和显示名称。

• 实现选择器：

  该属性用于选择 PrincipalMapper 接口的实现。默认实现会从特定的 claim 路径中提取字段。

  polaris.oidc.principal-mapper.type=default

• 默认实现的配置属性：

  polaris.oidc.principal-mapper.id-claim-path=polaris/principal_id
  polaris.oidc.principal-mapper.name-claim-path=polaris/principal_name

• 可以针对每个 OIDC 租户单独覆盖。

角色映射

• 接口：PrincipalRolesMapper

  Polaris 使用该组件将 OIDC 令牌中的角色 claims 转换为 Polaris 角色。

• Quarkus OIDC 配置：

  该设置用于告知 Quarkus 在 OIDC 令牌中的什么位置查找角色。

  quarkus.oidc.roles.role-claim-path=polaris/roles

• 实现选择器：

  该属性用于选择 PrincipalRolesMapper 的实现。default 实现会对 OIDC 角色应用正则表达式（regex）转换。

  polaris.oidc.principal-roles-mapper.type=default

• 默认实现的配置属性：

  polaris.oidc.principal-roles-mapper.filter=^(?!profile$|email$).*
  polaris.oidc.principal-roles-mapper.mappings[0].regex=^.*$
  polaris.oidc.principal-roles-mapper.mappings[0].replacement=PRINCIPAL_ROLE:$0