搭配 SPIFFE 使用 WIF

SPIFFE 是 CNCF 用於向工作負載簽發身分的標準。SPIRE 是其開源參考實作，另有數款商業產品也會簽發符合 SPIFFE 規範的身分。Anthropic 可與任何發出相容於 OIDC 之 JWT-SVID 的 SPIFFE 實作進行聯合。聯合可透過位於公開 HTTPS URL 的 OIDC 探索文件運作（discovery 模式；請參閱 URL 限制），或透過直接註冊 JWKS 運作（inline 模式）。JWT-SVID 規格將 sub 定義為工作負載的 SPIFFE ID，而 SPIFFE Workload API 要求呼叫者在擷取時提供 aud，因此這些宣告在各實作間是一致的。Anthropic 額外要求 iss 和 iat，而 JWT-SVID 規格並未強制要求這兩者，因此請設定您的實作以填入這兩個欄位（在 SPIRE 中，iss 是 jwt_issuer 伺服器設定，而 iat 會自動設定）。完成上述設定後，本指南的設定 Anthropic、取得並使用權杖以及限定規則範圍各節適用於任何 SPIFFE 實作。如需最新清單，請參閱 SPIFFE 專案網站上的實作 SPIFFE 的商業軟體。

SPIFFE 為每個工作負載指派一個格式為 spiffe://<trust-domain>/<path> 的穩定身分 URI，而 SPIRE 會透過 Workload API 依需求將該身分簽發為 JWT-SVID。JWT-SVID 是一個普通的已簽署 JWT，其 sub 宣告是工作負載的 SPIFFE ID，而 aud 宣告則由工作負載在擷取時提供。

從 SPIRE 信任網域到標準 OIDC 的橋接是 SPIRE OIDC Discovery Provider，這是一個獨立的輔助程式，會為信任網域的 JWT 簽署金鑰發布 /.well-known/openid-configuration 和 JWKS 端點。當探索提供者執行時，JWT-SVID 的驗證方式與任何其他 OIDC 權杖相同：將探索 URL 註冊為聯合發行者、撰寫符合工作負載 SPIFFE ID 的聯合規則，並讓工作負載向 Anthropic 的權杖交換端點出示其 JWT-SVID。

本頁的範例使用 SPIRE，適用於任何執行 SPIRE Agent 的環境：Kubernetes Pod、虛擬機器和裸機主機。

先決條件

• 熟悉 WIF 概念：服務帳戶、聯合發行者和聯合規則。
• 已簽發工作負載身分的 SPIFFE 部署（本頁範例使用 SPIRE Server 和 Agent），以及需要呼叫 Claude API 之工作負載的註冊項目。
• 信任網域的 OIDC 探索端點（在 SPIRE 中為 OIDC Discovery Provider），並以可公開存取的 HTTPS 端點執行，或已匯出 JWKS 以供 inline 註冊使用。
• 您的 SPIFFE 發行者已設定為將 JWT-SVID 上的 iss 宣告設為您將註冊為聯合發行者 issuer_url 的值。對於 discovery 模式，這是探索端點的公開 URL（在 SPIRE 中為 jwt_issuer 伺服器設定）。
• 您的工作負載可取得 JWT-SVID。WIF 僅接受 JWT-SVID；不使用 X.509-SVID。
• 在 Claude Console 中為您的 Anthropic 組織建立服務帳戶、聯合發行者和聯合規則的權限。

擷取 JWT-SVID 時要請求的受眾值一律為 https://api.anthropic.com。請在 spiffe-helper 的 jwt_audience、Workload API 的 FetchJWTSVID 呼叫以及聯合規則的 audience 比對器中使用此值。

設定 SPIRE

本節的說明專屬於 SPIRE。如果您使用不同的 SPIFFE 發行者，請依照其自身的文件設定其 OIDC 探索端點和 JWT-SVID 擷取，然後繼續進行設定 Anthropic。

如果您已在執行搭配 OIDC Discovery Provider 的 SPIRE，與 Anthropic 聯合在 SPIRE 端需要三件事：與探索 URL 相符的 jwt_issuer、將呼叫 Claude API 之工作負載的註冊項目，以及讓該工作負載以 Anthropic 受眾擷取 JWT-SVID 的方法。以下各小節將逐一說明。設定片段僅顯示與 Anthropic 聯合相關的設定；它們並非完整的 SPIRE 部署設定。

驗證 JWT 發行者

Anthropic 透過將 JWT-SVID 的 iss 宣告與已註冊的聯合發行者比對，並從該發行者的探索文件擷取 JWKS 來驗證 JWT-SVID。兩個 SPIRE 設定必須指向相同的 URL：SPIRE Server 的 jwt_issuer（會成為每個簽發之 JWT-SVID 中的 iss 宣告）以及 OIDC Discovery Provider 的 domains 清單（決定提供探索文件和 JWKS 的主機）。該共用 URL 即為您向 Anthropic 註冊的內容。

信任網域和發行者 URL 是獨立的。信任網域（spiffe://prod.example.com）限定 sub 宣告的範圍；發行者 URL（https://oidc-discovery.prod.example.com）是 Anthropic 擷取簽署金鑰的位置。兩者不需要共用主機名稱。

確認 SPIRE Server 的設定中已設定 jwt_issuer，並指向探索提供者的公開 URL。以下範例也顯示了預設的 JWT-SVID 存留期；SPIRE 的內建預設值為 5 分鐘，這短到需要持續輪替（請參閱執行 spiffe-helper）。Anthropic 的權杖交換端點會拒絕任何存留期超過聯合發行者所設定上限（預設為 1 小時；請參閱驗證規則）的身分權杖。此檢查適用於每個 SPIFFE 實作，而非僅限 SPIRE，因此請將 default_jwt_svid_ttl（或任何個別項目的覆寫值）維持在該上限以內。

server {
    trust_domain         = "prod.example.com"
    jwt_issuer           = "https://oidc-discovery.prod.example.com"
    default_jwt_svid_ttl = "5m"
    # ...
}

在 OIDC Discovery Provider 的設定中，相同的主機名稱必須出現在 domains 下，且提供者必須能夠連線到 SPIRE Server 的 API 通訊端。提供者透過 HTTPS 提供探索文件和 JWKS；可使用其內建的 ACME 支援終止 TLS，或在其前方放置負責此工作的負載平衡器。

domains = ["oidc-discovery.prod.example.com"]

server_api {
    address = "unix:///run/spire/sockets/private/api.sock"
}

acme {
    email        = "[email protected]"
    tos_accepted = true
}

註冊工作負載

每個呼叫 Claude API 的工作負載都需要一個 SPIRE 註冊項目，將其執行階段選擇器對應到 SPIFFE ID。如果工作負載已註冊，請記下其 SPIFFE ID；您會在聯合規則的 subject_prefix 中使用它。如果尚未註冊，請進行註冊。對於 Kubernetes Pod，選擇器通常是命名空間和 Kubernetes 服務帳戶：

spire-server entry create \
    -spiffeID spiffe://prod.example.com/ns/inference/sa/worker \
    -parentID spiffe://prod.example.com/spire/agent/k8s_psat/prod-cluster/NODE_UID \
    -selector k8s:ns:inference \
    -selector k8s:sa:worker

Kubernetes 以外的工作負載使用主機層級的選擇器，例如 unix:uid:1000（unix:path 也可用，但需要在代理程式的 unix 工作負載證明器設定中設定 discover_workload_path = true）。執行 spire-controller-manager 的叢集可以使用 ClusterSPIFFEID 自訂資源宣告項目，而非直接呼叫 spire-server entry create。

執行 spiffe-helper

spiffe-helper 是一個 sidecar 公用程式，會連接到 SPIRE Agent 通訊端、為指定受眾擷取 JWT-SVID、將其寫入檔案，並在到期前重新擷取。此輔助程式預設以常駐程式模式執行；以下範例明確設定 daemon_mode = true。

agent_address = "/run/spire/sockets/agent.sock"
cert_dir      = "/var/run/secrets/anthropic.com"
daemon_mode   = true

jwt_svids = [{
    jwt_audience       = "https://api.anthropic.com"
    jwt_svid_file_name = "token"
}]

在 Kubernetes 中，將 spiffe-helper 作為 sidecar 容器執行，與您的應用程式容器共用記憶體支援的 emptyDir 磁碟區（medium: Memory），使持有者 SVID 永遠不會落在節點的磁碟上。將 SPIRE Agent 通訊端從主機掛載到 sidecar 中，在兩個容器中將共用磁碟區掛載於 /var/run/secrets/anthropic.com，並在應用程式容器上設定 ANTHROPIC_IDENTITY_TOKEN_FILE=/var/run/secrets/anthropic.com/token。在 VM 和裸機上，將 spiffe-helper 作為系統服務與工作負載一併執行，並將兩者指向共用目錄。

設定 Anthropic

依照設定逐步說明在 Claude Console 中註冊聯合發行者、建立 Anthropic 服務帳戶並建立聯合規則。請使用以下 SPIFFE 專屬的值。

聯合發行者： 以 discovery 模式註冊 OIDC Discovery Provider 的公開 URL。Anthropic 會從此 URL 擷取 /.well-known/openid-configuration，並依照傳回的 jwks_uri 擷取信任網域的簽署金鑰。

{
  "name": "spire-prod",
  "issuer_url": "https://oidc-discovery.prod.example.com",
  "jwks": { "type": "discovery" }
}

如果探索提供者無法從公開網際網路存取，請自行擷取 JWKS（curl https://oidc-discovery.prod.example.com/keys），並使用傳回之 keys 陣列的內容，以 "jwks": {"type": "inline", "keys": [...]} 註冊發行者。在 inline 模式下，issuer_url 僅用於與 JWT-SVID 的 iss 宣告比對；Anthropic 絕不會嘗試連線到該 URL。

若要在不公開探索端點的情況下自動更新 JWKS，請設定 SPIRE Server 的 BundlePublisher 外掛程式（aws_s3、gcp_cloudstorage 或 k8s_configmap）並搭配 format = "jwks"，以在每次輪替時將 JWT 簽署金鑰推送到外部儲存空間，然後將其同步到發行者的內嵌金鑰中。

聯合規則： 比對 JWT-SVID 的 sub（SPIFFE ID）以及您設定 spiffe-helper 請求的 aud。SPIFFE ID 是 URI 字串，而 subject_prefix 會將其視為不透明文字進行比對，因此精確值或結尾為 * 的前置詞比對都適用。對於更複雜的模式，請使用 CEL condition。

{
  "name": "spire-inference-worker",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "spiffe://prod.example.com/ns/inference/sa/worker",
    "audience": "https://api.anthropic.com"
  },
  "target": {
    "type": "service_account",
    "service_account_id": "svac_..."
  },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

請盡可能依工作負載所允許的範圍精確設定。僅當該路徑下註冊的每個工作負載都應對應到同一個 Anthropic 服務帳戶時，才將 subject_prefix 放寬為 spiffe://prod.example.com/ns/inference/*。將規則的 fdrl_... ID 新增到工作負載的 ANTHROPIC_FEDERATION_RULE_ID 環境變數。

取得並使用權杖

Anthropic SDK 可以從 spiffe-helper 維護的檔案讀取 JWT-SVID，或透過權杖提供者可呼叫物件直接呼叫 SPIFFE Workload API。檔案路徑是最簡單的整合方式，適用於每種 SDK 語言；可呼叫物件路徑可省去 sidecar，但需要您的應用程式語言中有 SPIFFE Workload API 用戶端。

驗證設定

在接入 SDK 之前，請直接從 SPIRE Agent 擷取 JWT-SVID，並確認宣告符合您的聯合規則所預期的內容。如果您使用不同的 SPIFFE 實作，請使用其 CLI 或 Workload API 用戶端擷取 JWT-SVID，並以相同方式解碼酬載。

spire-agent api fetch jwt \
    -audience https://api.anthropic.com \
    -socketPath /run/spire/sockets/agent.sock \
    -output json \
  | jq -r '.[0].svids[0].svid' \
  | jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson'

-output json 旗標會將 SVID 回應和套件組合回應以兩元素 JSON 陣列的形式傳回，因此 jq -r '.[0].svids[0].svid' 可擷取純權杖。在沒有 -output 的較舊 SPIRE 版本上，該命令會改為列印帶標籤的區塊；在這種情況下，請將預設輸出透過管道傳送至 awk '/^[[:space:]]*eyJ/{print $1; exit}' 以擷取權杖行。檢查 iss 是否為您註冊的 OIDC Discovery Provider URL、sub 是否為工作負載的 SPIFFE ID，以及 aud 是否包含 https://api.anthropic.com。然後執行取得並使用權杖中的 cURL 範例；成功的交換會傳回以 sk-ant-oat01- 開頭的 access_token。若出現 400 invalid_grant，請參閱疑難排解失敗的交換；SPIRE 端最常見的原因是 SPIRE Server 的 jwt_issuer 與註冊為聯合發行者的 URL 不符。

限定規則範圍

SPIFFE ID 路徑慣例由操作者定義，因此聯合規則的 subject_prefix 比對器應反映您的註冊項目所使用的路徑配置。常見的配置包括 spiffe://<trust-domain>/ns/<namespace>/sa/<service-account>（spire-controller-manager 中 ClusterSPIFFEID 資源發出的預設值）以及用於 VM 和裸機工作負載的 spiffe://<trust-domain>/host/<hostname>/<service>。

將規則的 match 區塊鎖定在符合您使用案例的最窄範圍：

• 釘選到單一工作負載： 將 subject_prefix 設為完整的 SPIFFE ID，且結尾不帶 *。
• 一律設定受眾： 在規則上要求 audience，並以相同的值設定 spiffe-helper（或 Workload API 呼叫），以拒絕為其他依賴方簽發的 SVID。
• 依路徑區段限定範圍： 使用 spiffe://prod.example.com/ns/inference/* 授予在某命名空間下註冊的每個工作負載，並為每個命名空間建立個別的規則和 Anthropic 服務帳戶，而非擴大單一規則的範圍。
• 每個信任網域一個發行者： 每個 SPIRE 信任網域都有自己的簽署金鑰和 OIDC Discovery Provider。請將每個都註冊為個別的聯合發行者，並將規則繫結到擁有其所比對之 SPIFFE ID 的發行者。

後續步驟

• Workload Identity Federation：概念、權杖交換流程和 SDK 設定選項。
• WIF 參考：環境變數、JWKS 來源模式和規則比對模式。
• 搭配 Kubernetes 使用 WIF：適用於使用原生投影服務帳戶權杖而非 SPIRE 的叢集。