搭配 Okta 使用 WIF

Okta 可以透過 OAuth 2.0 client_credentials 授權類型向服務應用程式核發 OIDC 存取權杖，藉此作為工作負載身分提供者。您的工作負載向 Okta 進行驗證（通常使用 private_key_jwt，因此不會儲存共用密鑰），接收已簽署的「JSON Web Token」（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、存取政策，以及您想要比對的任何自訂宣告（claim）。

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

1. 建立服務應用程式整合。 在 Okta Admin Console 中，建立類型為 API Services（OIDC，機器對機器）的新應用程式整合。記下產生的 Client ID。
2. 設定用戶端驗證。 若要採用無金鑰設定，請選擇 Public key / Private key（private_key_jwt）並註冊您工作負載的公開 JWK。或者，如果您的環境可以安全地儲存用戶端密鑰，也可以使用用戶端密鑰。在以下範例中，您可能需要停用應用程式上的 DPoP 要求；請確保您的正式環境設定符合貴組織的安全要求。
3. 設定 audience。 在您的自訂授權伺服器上，將 audience 設定為 https://api.anthropic.com，使核發的存取權杖帶有該 aud 宣告。Anthropic 會根據此固定值驗證 aud。
4. 授予 scope。 在您的自訂授權伺服器上，確保至少存在一個服務應用程式被允許請求的 scope（例如 anthropic.access）。Okta 會拒絕未包含已授予 scope 的 client_credentials 請求。
5. 建立存取政策。 在您的自訂授權伺服器上，建立一個存取政策，其中至少包含一條規則，允許您的服務應用程式請求您在步驟 4 中授予的 scope。
6. （選用）新增自訂宣告。 如果您想要比對 client 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 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",
            # 建構以您的 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 值。若出現 400 invalid_grant，請參閱疑難排解失敗的交換；最常見的 Okta 端原因是 issuer_url 不相符（它必須包含 /oauth2/<auth-server-id> 路徑；Okta 組織授權伺服器無法使用）。



限縮規則範圍

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

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



後續步驟

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