GCPCredentialsControllerService

GCPCredentialsControllerService 集中管理所有与 Google Cloud 交互的 Lynxus 组件所使用的认证策略。每种策略只暴露自己需要的属性，让管理员 无需改动下游 Processor 即可切换方式。本指南概述所有受支持的策略。

Application Default Credentials

Application Default Credentials（ADC）让 Lynxus 继承运行时环境提供的 凭据，包括：

• 引用服务账号密钥文件的 GOOGLE_APPLICATION_CREDENTIALS 环境变量
• 开发机上的 gcloud auth application-default login
• Cloud Shell 或其他自动注入 ADC 的 Google 托管环境

不需要额外属性。请确认提供 ADC 令牌的账号具备引用该 Controller Service 的 Processor 所需的 IAM 角色。

Service Account Credentials（JSON 文件）

当服务账号密钥材料存储在磁盘上时使用该策略。把 Service Account JSON File 属性配置为指向 JSON 密钥文件。Lynxus 在启用该 Controller Service 时读取文件并缓存 Google 凭据。

最佳实践

• 限制文件系统权限，确保只有 Lynxus 服务用户可以读取密钥。
• 定期轮换密钥，并在 Google Cloud Console 中删除未使用的密钥。
• 模拟（impersonate）域用户时，把 Delegation Strategy 设为 Delegated Account 并提供 Delegation User，让 Lynxus 代表 该用户调用 Google API。

Service Account Credentials（JSON 值）

该策略把整个服务账号 JSON 文档直接嵌入 Controller Service 属性。 该值被标记为敏感值，可以通过参数上下文（Parameter Context）注入， 把凭据与流程定义分离。

最佳实践

• 把 JSON 值存放在该属性引用的参数上下文中，以便按环境切换凭据。
• 使用 lynxus.properties 中 Lynxus 的敏感属性加密功能，对磁盘上 存储的 JSON 加密。

Compute Engine Credentials

当 Lynxus 运行在 Google 托管的运行时（Compute Engine、GKE 等）上， 应使用实例绑定的服务账号时，选择 Compute Engine Credentials。 Google 会自动刷新 metadata 服务器令牌，因此不需要额外属性。

最佳实践

• 只给实例服务账号授予流程所需的角色。
• 如果多个 Lynxus 节点共享同一实例模板，请确认所有节点都拥有相同 的 IAM 权限，或配置 Workload Identity Federation 以实现更细的管控。

Workload Identity Federation

Workload Identity Federation（WIF）通过 Google 的 Security Token Service（STS），把外部身份提供者的令牌交换为短期 Google Cloud 访问令牌。该 Controller Service 配置 Google 的 IdentityPoolCredentials，让 Google 客户端库自动刷新 Google Cloud 令牌。

1. 在 Google Cloud 中配置 Workload Identity Federation

# 创建 pool（每个环境只需一次）
gcloud iam workload-identity-pools create lynxus-pool \
  --project=MY_PROJECT_ID \
  --location=global \
  --display-name="Lynxus Pool"

# 创建绑定你的 IdP 的 provider（以名为 myidp 的 OIDC 为例）
gcloud iam workload-identity-pools providers create-oidc myidp \
  --project=MY_PROJECT_ID \
  --location=global \
  --workload-identity-pool=lynxus-pool \
  --display-name="My Identity Provider" \
  --issuer-uri="https://identity.myidp.com/oauth2/..." \
  --allowed-audiences="//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/lynxus-pool/providers/myidp" \
  --attribute-mapping="google.subject=assertion.sub"

记下命令打印的 audience 字符串，必须原样复制到 Lynxus 的 Audience 属性：

//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/lynxus-pool/providers/myidp

2. 为 workload identity 主体授权 Google Cloud 资源

STS 签发的访问令牌代表的是 workload identity 主体本身。在项目或 特定资源上为该身份授予 IAM 角色：

# 项目范围
gcloud projects add-iam-policy-binding MY_PROJECT_ID \
  --member="principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/lynxus-pool/subject/IDENTITY_SUBJECT" \
  --role="roles/storage.objectViewer"

# 桶范围（示例）
gcloud storage buckets add-iam-policy-binding gs://MY_BUCKET \
  --member="principal://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/lynxus-pool/subject/IDENTITY_SUBJECT" \
  --role="roles/storage.objectViewer"

IDENTITY_SUBJECT 必须与你在 provider 中映射的声明（例如 assertion.sub）一致。目前不支持服务账号模拟，因此请直接向 workload identity 主体授予角色。

3. 配置 Lynxus 属性（选择 Workload Identity 策略）

这些属性设置完成后，启用 GCPCredentialsControllerService。引用它的 Processor 会立即获得 IdentityPoolCredentials，Google 的库会使用 配置的 subject-token provider 自动刷新访问令牌。

验证流程

1. 启用或刷新 Subject Token Provider Controller Service。
2. 在 GCPCredentialsControllerService 上使用 Verify 操作。验证成功 表明 Lynxus 可以使用配置的代理、audience 和 scope 与 Google STS 交换 subject token。
3. 启用依赖的 Processor。不需要其他 Controller Service。

故障排查

所有策略都可以在单个 Controller Service 配置中切换，Lynxus 用户可以 在服务账号密钥、Compute Engine、Application Default Credentials 和 Workload Identity Federation 之间迁移，无需引入新的 Controller Service 或更新 Processor 属性。只需调整一次认证策略，所有依赖的 Processor 会自动使用新凭据。