搭配 Okta 使用 WIF

Okta 可以作為工作負載身分提供者，透過 OAuth 2.0 client_credentials 授權向服務應用程式簽發 OIDC 存取權杖。您的工作負載向 Okta 進行驗證（通常使用 private_key_jwt，因此不會儲存共用密鑰），接收已簽署的「JSON Web Token」（JSON 網路權杖），即 JWT，然後將該 JWT 與 Anthropic 交換以取得短期存取權杖。

Okta 授權伺服器的簽發者 URL 格式為 https://<your-domain>.okta.com/oauth2/<auth-server-id>。如果您使用內建的預設伺服器，路徑為 /oauth2/default。

設定和驗證 Okta 的方式有很多種，這些內容超出本文件的範圍。請確保您的設定和驗證機制遵循貴公司的指引和安全實務。

先決條件

• 熟悉 WIF 概念：服務帳戶、聯合簽發者和聯合規則。
• 已啟用 API Access Management 的 Okta 組織（自訂授權伺服器所需）。
• 在 Claude Console 中為您的 Anthropic 組織建立服務帳戶、聯合簽發者和聯合規則的權限。
• 能夠向 Okta 的 /v1/token 端點請求權杖並連線至 api.anthropic.com 的工作負載。

設定 Okta

概括而言，您需要：

1. 建立 Okta 服務應用程式。
2. 設定您的預設授權伺服器（或建立新的自訂授權伺服器），包含受眾（audience）、範圍（scope）、存取原則，以及您想要用於比對的任何自訂宣告（claims）。

確切的導覽方式取決於您的 Okta 組織設定和管理主控台版本。以下編號步驟說明一種常見的路徑：

1. 建立服務應用程式整合。 在 Okta Admin Console 中，建立類型為 API Services（OIDC，機器對機器）的新應用程式整合。記下產生的 Client ID。
2. 設定用戶端驗證。 若要採用無金鑰設定，請選擇 Public key / Private key（private_key_jwt）並註冊您工作負載的公開 JWK。或者，如果您的環境可以安全地儲存用戶端密鑰，也可以使用用戶端密鑰。對於以下範例，您可能需要在應用程式上停用 DPoP 要求；請確保您的正式環境設定符合貴組織的安全要求。
3. 設定受眾。 在您的自訂授權伺服器上，將受眾設定為 https://api.anthropic.com，以便簽發的存取權杖帶有該 aud 宣告。Anthropic 會根據此固定值驗證 aud。
4. 授予範圍。 在您的自訂授權伺服器上，確保至少存在一個允許服務應用程式請求的範圍（例如 anthropic.access）。Okta 會拒絕未包含已授予範圍的 client_credentials 請求。
5. 建立存取原則。 在您的自訂授權伺服器上，建立一個存取原則，其中至少包含一條規則，允許您的服務應用程式請求您在步驟 4 中授予的範圍。
6. （選用）新增自訂宣告。 如果您想要比對用戶端 ID 以外的內容，請在授權伺服器的 Claims 分頁中為存取權杖新增宣告。

對於使用 client_credentials 的服務應用程式，Okta 會將簽發的存取權杖的 sub 宣告設定為應用程式的 Client ID，並將 iss 設定為授權伺服器的簽發者 URL。

設定 Anthropic

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

聯合簽發者： 使用您的 Okta 自訂授權伺服器 URL 和探索模式。Anthropic 會讀取 Okta 的 .well-known/openid-configuration 探索文件，並從其公告的 jwks_uri 擷取 JWKS。

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks_source": "discovery"
}

聯合規則： 比對 Okta 的 sub 宣告，即服務應用程式的 Client ID。如果您在 Okta 中定義了自訂宣告，可以改用 claims 對應或 CEL condition 來比對這些宣告。

{
  "name": "okta-pipeline",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "0oa1b2c3d4e5f6g7h8i9",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}

取得權杖並呼叫 Claude API

與平台原生提供者（AWS、Google Cloud、Kubernetes）不同，這些提供者會在工作負載的執行環境中提供權杖（透過投影檔案或本機中繼資料端點），而 Okta 不會。您的工作負載必須呼叫 Okta 的權杖端點以取得 JWT，然後將該 JWT 作為身分權杖傳遞給 Anthropic SDK。

import os
import httpx
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx.post(
        f"{os.environ['OKTA_ISSUER']}/v1/token",
        data={
            "grant_type": "client_credentials",
            "scope": "anthropic.access",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            # 建立 RFC 7523 client_assertion JWT，並使用您的 Okta 應用程式私密金鑰進行簽署
            "client_assertion": build_signed_client_assertion(),
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_okta_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

每個 SDK 分頁都展示了可呼叫的模式：每當 Anthropic 存取權杖接近到期時，Anthropic SDK 會再次呼叫您的身分權杖提供者，因此您的 Okta 擷取器應在每次呼叫時傳回新的權杖，而不是無限期快取同一個權杖。ant CLI 會在每次交換時重新讀取 ANTHROPIC_IDENTITY_TOKEN_FILE，因此對於長時間執行的 shell，請定時重新整理該檔案。

驗證設定

成功的交換會傳回以 sk-ant-oat01- 開頭的 access_token 以及以秒為單位的 expires_in 值。若遇到 400 invalid_grant，請參閱疑難排解失敗的交換；Okta 端最常見的原因是 issuer_url 不符（必須包含 /oauth2/<auth-server-id> 路徑；Okta 組織授權伺服器無法使用）。

限定規則範圍

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

• 固定確切的 Client ID： 將 subject_prefix 設定為服務應用程式的完整 Client ID，且不帶結尾的 *。
• 固定受眾： 比對您在授權伺服器上設定的 audience 值，以便拒絕為不同受眾簽發的權杖。
• 比對自訂宣告： 若需更細緻的範圍限定，請在授權伺服器的 Claims 分頁中新增宣告，並使用規則的 claims 對應或 CEL condition 來比對這些宣告。
• 每個服務應用程式使用一條規則： 為每個服務應用程式建立獨立的聯合規則，而不是讓多個應用程式共用一條規則。

後續步驟

• 查閱 WIF 參考資料以了解完整的憑證解析順序和設定檔配置。
• 參閱 WIF 參考資料以使用 CEL 運算式比對自訂 Okta 宣告。