搭配 Okta 使用 WIF

Okta 可以透過 OAuth 2.0 client_credentials 授權類型向服務應用程式（service application）核發 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 中，開啟 Settings → Workload identity，點擊 Connect workload，然後選擇 Custom OIDC。精靈會引導您完成註冊簽發者、建立服務帳戶以及建立聯合規則。

精靈會為您建立這些資源。無論您是在精靈中輸入這些值，還是將它們傳送至 Admin API，請使用下列值：

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

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks": { "type": "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 httpx2
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx2.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",
            # 建立以您 Okta 應用程式私鑰簽署的 RFC 7523 client_assertion JWT
            "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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

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

驗證設定

成功的交換會回傳一個以 sk-ant-oat01- 開頭的 access_token，以及以秒為單位的 expires_in 值。如果交換失敗並回傳不透明的 401 authentication_error 回應（訊息為 Authentication failed），請查看驗證歷史記錄頁面以了解拒絕原因，並參閱疑難排解失敗的交換；Okta 端最常見的原因是 issuer_url 不符（它必須包含 /oauth2/<auth-server-id> 路徑；Okta 組織授權伺服器無法使用）。

限定規則範圍

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

• 固定確切的 Client ID： 將 subject_prefix 設為服務應用程式的完整 Client ID，結尾不加 *。
• 固定受眾： 比對您在授權伺服器上設定的 audience 值，使為其他受眾鑄造的權杖遭到拒絕。
• 比對自訂宣告： 若需更細緻的範圍限定，請在授權伺服器的 Claims 分頁中新增宣告，並以規則的 claims 對應或 CEL condition 進行比對。
• 每個服務應用程式使用一條規則： 為每個服務應用程式建立個別的聯合規則，而非在多個應用程式之間共用一條規則。

後續步驟

• 檢閱 WIF 參考文件以了解完整的憑證解析順序與設定檔設定。
• 參閱 WIF 參考文件以使用 CEL 運算式比對自訂 Okta 宣告。