身份认证

本页介绍在使用 Helm Chart 部署时，如何为 Polaris 配置身份认证。

概述

Polaris 支持三种身份认证模式：

模式	类型	说明
内部模式	`internal`	由 Polaris 管理凭据并签发令牌。默认模式。
外部模式	`external`	由外部身份提供方（IDP）签发令牌，Polaris 通过 OIDC 对其进行验证。
混合模式	`mixed`	同时启用内部和外部身份认证。

有关 Polaris 身份认证的更多信息，请参阅文档中的身份提供方章节。

内部身份认证

内部身份认证是默认模式。Polaris 管理用户凭据，并使用 RSA 密钥对或对称密钥签发 JWT 令牌。

⚠️ 警告

在多副本的生产环境中，所有 Polaris Pod 必须共享相同的令牌签名密钥。默认的 Chart 会为每个 Pod 生成随机密钥，这将导致令牌验证失败。

RSA 密钥对（推荐）

RSA 密钥对提供非对称加密，允许分发公钥以用于令牌验证。

生成 RSA 密钥对并创建 Kubernetes Secret：

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

kubectl create secret generic polaris-token-keys \
  --namespace polaris \
  --from-file=private.pem \
  --from-file=public.pem

将 chart 配置为使用 RSA 密钥对：

authentication:
  type: internal
  tokenBroker:
    type: rsa-key-pair
    secret:
      name: "polaris-token-keys"
      rsaKeyPair:
        publicKey: "public.pem"
        privateKey: "private.pem"

对称密钥

对称密钥在签名和验证时使用相同的密钥。

生成一个对称密钥并创建 Kubernetes Secret：

openssl rand -base64 32 > symmetric.key

kubectl create secret generic polaris-token-keys \
  --namespace polaris \
  --from-file=symmetric.key

配置 Chart：

authentication:
  type: internal
  tokenBroker:
    type: symmetric-key
    secret:
      name: "polaris-token-keys"
      symmetricKey:
        secretKey: "symmetric.key"

令牌有效期

配置令牌的最长有效期：

authentication:
  tokenBroker:
    maxTokenGeneration: PT1H  # 1 hour (ISO 8601 duration)

外部身份认证（OIDC）

外部身份认证将令牌的签发委托给支持 OpenID Connect（OIDC）的外部身份提供方（IDP）。Polaris 使用该 IDP 的公钥来验证令牌。

Polaris 可与任何符合 OIDC 规范的身份提供方配合使用。

基本配置

要启用外部身份认证：

authentication:
  type: external

oidc:
  authServeUrl: "https://your-idp.example.com/realms/polaris"
  client:
    id: polaris

配置客户端密钥

如果你的 IDP 在进行令牌自省时需要客户端密钥：

kubectl create secret generic polaris-oidc-client \
  --namespace polaris \
  --from-literal=clientSecret='your-client-secret'

authentication:
  type: external

oidc:
  authServeUrl: "https://your-idp.example.com/realms/polaris"
  client:
    id: polaris
    secret:
      name: "polaris-oidc-client"
      key: "clientSecret"

主体映射

配置 Polaris 如何将 OIDC 令牌声明（claims）映射到 Polaris 主体：

oidc:
  principalMapper:
    type: default
    idClaimPath: "sub"                   # Claim containing the principal ID
    nameClaimPath: "preferred_username"  # Claim containing the principal name

对于嵌套的声明（claim），请使用 / 作为分隔符：

oidc:
  principalMapper:
    idClaimPath: "polaris/principal_id"
    nameClaimPath: "polaris/principal_name"

角色映射

配置 Polaris 如何将 OIDC 令牌声明映射到 Polaris 角色：

oidc:
  principalRolesMapper:
    type: default
    rolesClaimPath: "realm_access/roles"  # Path to roles in the token

角色过滤

过滤令牌中传递给 Polaris 的角色：

oidc:
  principalRolesMapper:
    filter: "^POLARIS_.*"  # Only include roles starting with POLARIS_

角色名称转换

使用正则表达式映射，将身份提供方（IDP）格式的角色名称转换为 Polaris 格式：

oidc:
  principalRolesMapper:
    mappings:
      - regex: "^role_(.*)"
        replacement: "PRINCIPAL_ROLE:$1"
      - regex: "^admin$"
        replacement: "PRINCIPAL_ROLE:service_admin"

默认的 Polaris 认证器要求角色采用 PRINCIPAL_ROLE:<role_name> 的格式。

完整示例

authentication:
  type: external

oidc:
  authServeUrl: "https://keycloak.example.com/realms/polaris"
  client:
    id: polaris
    secret:
      name: "polaris-oidc-client"
      key: "clientSecret"
  principalMapper:
    idClaimPath: "sub"
    nameClaimPath: "preferred_username"
  principalRolesMapper:
    rolesClaimPath: "realm_access/roles"
    mappings:
      - regex: "^polaris_(.*)"
        replacement: "PRINCIPAL_ROLE:$1"

混合认证

混合模式同时启用内部认证和外部认证。该模式适用于从内部认证迁移到外部认证的过渡阶段，或者部分客户端使用内部凭据而其他客户端使用外部令牌的场景。

authentication:
  type: mixed
  tokenBroker:
    type: rsa-key-pair
    secret:
      name: "polaris-token-keys"
      rsaKeyPair:
        publicKey: "public.pem"
        privateKey: "private.pem"

oidc:
  authServeUrl: "https://your-idp.example.com/realms/polaris"
  client:
    id: polaris

按 Realm 划分的认证

你可以为不同的 Realm 配置各自的认证设置：

authentication:
  type: internal  # Default for all realms
  realmOverrides:
    production:
      type: external
    staging:
      type: mixed

高级配置

对于 chart 值中未涵盖的高级 OIDC 配置，可使用 advancedConfig 部分直接传入 Quarkus OIDC 属性：

advancedConfig:
  quarkus.oidc.token.issuer: "https://your-idp.example.com"
  quarkus.oidc.token.audience: "polaris-api"
  quarkus.oidc.authentication.scopes: "openid,profile,email"

有关所有可用选项，请参阅 Quarkus OIDC 配置参考。

禁用令牌服务

当完全使用外部身份认证时，可以禁用内部令牌服务：

authentication:
  type: external
  tokenService:
    type: disabled

这会阻止 Polaris 签发令牌，并确保所有身份验证都通过外部 IDP 进行。

认证