在自託管環境中驗證工作階段身分

驗證 CLAUDE_CODE_SESSION_ACCESS_TOKEN JWT，以便您網路上的服務可以信任來自自託管環境中工作階段的請求。

自託管環境讓 Claude Code 雲端工作階段在您操作的基礎設施上執行，而不是在 Anthropic 的基礎設施上執行。由於工作階段在您的網路內執行，Claude 可以直接呼叫您的內部服務。這些服務需要一種方式來確認請求來自您環境中的 Claude Code 工作階段，並識別建立該工作階段的使用者或服務身分。

自託管環境中的每個工作階段都會在 CLAUDE_CODE_SESSION_ACCESS_TOKEN 環境變數中收到一個簽署的 JSON Web Token (JWT)。工作階段會像任何持有人認證一樣呈現令牌；例如，Claude 執行的指令碼可以使用 curl -H "Authorization: Bearer $CLAUDE_CODE_SESSION_ACCESS_TOKEN" 呼叫您的服務。Anthropic 簽署令牌並在公開 JWKS 端點發佈驗證金鑰。您的服務會擷取這些金鑰、驗證簽章，並讀取宣告以決定要授予什麼存取權限。

工作階段令牌

在您編寫驗證程式碼之前，請了解令牌建立的內容以及您的 JWT 程式庫將看到的形狀。

令牌證明的內容

有效的令牌建立了一些事實，並刻意不建立其他事實：

• 證明：Anthropic 為特定環境中的特定工作階段簽發了令牌，以及工作階段的建立方式：由您組織中的使用者建立，或由您組織的服務身份建立，這是 Claude Tag 頻道工作階段的啟動方式
• 不證明：執行者主機上的哪個程序呈現它。令牌位於工作階段內的環境變數中，因此 Claude 執行的任何程式碼以及工作階段啟動的任何工具或 MCP 伺服器都可以讀取並呈現它。

對您的服務有兩個後果：

• 根據您的環境 ID（在雲端環境管理頁面上與您的環境一起顯示的 ccpool_... 值）驗證 aud 聲明，以拒絕簽發給任何其他組織環境的令牌。
• 將您從令牌衍生的認證範圍限制在單個編碼工作階段應該能夠執行的操作，而不是工作階段建立者可以執行的所有操作。請參閱範圍衍生認證。

令牌格式

CLAUDE_CODE_SESSION_ACCESS_TOKEN 的值具有 sk-ant-cc- 前綴，後面跟著標準的三部分 JWT：

sk-ant-cc-<base64url header>.<base64url payload>.<base64url signature>

在將值傳遞給 JWT 程式庫之前，請移除前綴。簽發給 Anthropic 託管雲端工作階段的令牌改為帶有 sk-ant-si- 前綴，並由不同的金鑰集簽署，因此拒絕任何不以 sk-ant-cc- 開頭的值。

簽名演算法是 ES256，這是 P-256 曲線上的 ECDSA，使用 SHA-256。令牌標頭帶有一個 kid，用於識別 JWKS 中的哪個金鑰簽署了它。

驗證令牌

驗證在兩個地方之一執行。您網路上的服務根據 Anthropic 發佈的金鑰對令牌進行密碼學驗證，工作階段內的包裝指令碼可以改為使用執行者二進位檔案的內建解碼器。

從您的服務驗證令牌

Anthropic 在公開、未經驗證的端點發佈驗證金鑰：

https://api.anthropic.com/v1/code/.well-known/jwks.json

回應是標準的 JSON Web Key Set。Anthropic 定期輪換簽署金鑰，輪換前的金鑰會在集合中保留足夠長的時間，以便它們簽署的令牌繼續驗證，因此不要固定單個金鑰。端點設定 Cache-Control: public, max-age=300，因此快取金鑰集並每五分鐘重新取得一次是安全的。

根據這些檢查驗證每個傳入令牌：

這些檢查直接對應到標準 JWT 程式庫。下面的範例使用 jose 在 Node.js 中實現完整序列，它處理 JWKS 取得、快取和 kid 選擇，以及在 Python 中使用 PyJWT 及其內建 JWKS 用戶端。

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
new URL("https://api.anthropic.com/v1/code/.well-known/jwks.json")
);

const PREFIX = "sk-ant-cc-";
const EXPECTED_POOL_ID = "ccpool_...";

export async function verifySessionToken(raw: string) {
if (!raw.startsWith(PREFIX)) {
throw new Error("not a self-hosted runner session token");
}
const jwt = raw.slice(PREFIX.length);

const { payload } = await jwtVerify(jwt, JWKS, {
issuer: "ccr",
audience: EXPECTED_POOL_ID,
algorithms: ["ES256"],
});

if (payload["ccr:role"] !== "session_worker") {
throw new Error("token is not a session_worker token");
}

const act = payload.act as { email?: string; sub?: string };
return {
sessionId: payload["ccr:session_id"] as string,
poolId: payload["ccr:pool_id"] as string,
orgId: payload["ccr:org_id"] as string,
creatorEmail: act?.email,
creatorSub: act?.sub,
};
}

import jwt
from jwt import PyJWKClient

JWKS_URL = "https://api.anthropic.com/v1/code/.well-known/jwks.json"
PREFIX = "sk-ant-cc-"
EXPECTED_POOL_ID = "ccpool_..."

jwks = PyJWKClient(JWKS_URL)


def verify_session_token(raw: str) -> dict:
if not raw.startswith(PREFIX):
raise ValueError("not a self-hosted runner session token")
token = raw.removeprefix(PREFIX)

signing_key = jwks.get_signing_key_from_jwt(token)
payload = jwt.decode(
token,
signing_key.key,
algorithms=["ES256"],
issuer="ccr",
audience=EXPECTED_POOL_ID,
)

if payload.get("ccr:role") != "session_worker":
raise ValueError("token is not a session_worker token")

act = payload.get("act") or {}
return {
"session_id": payload["ccr:session_id"],
"pool_id": payload["ccr:pool_id"],
"org_id": payload["ccr:org_id"],
"creator_email": act.get("email"),
"creator_sub": act.get("sub"),
}

在工作階段內驗證令牌

包裝指令碼在工作階段內執行，在 Claude 啟動之前。它們可以執行執行者二進位檔案的 self-hosted-runner decode-token 子命令，而不是呼叫 JWT 程式庫。子命令從位置引數、CLAUDE_CODE_SESSION_ACCESS_TOKEN 或管道 stdin 讀取令牌（按該順序），然後移除前綴、根據 JWKS 端點驗證簽名、檢查過期，並將聲明列印為 JSON。子命令僅執行簽名和過期檢查；它不檢查 iss、aud 或 ccr:role。當您的包裝器的驗證決定取決於這些聲明時，從列印的 JSON 讀取它們並明確比較它們。

此命令提取建立者身份，優先選擇 SSO 提供者的主體，然後是電子郵件地址，然後是建立者的 act.sub 主體 user:<id> 或 agent:<id>：

"$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token | jq -re '.act.attested_by.sub // .act.email // .act.sub'

包裝器在 CLAUDE_RUNNER_CLAUDE_BIN 中接收執行者自身二進位檔案的絕對路徑；使用該路徑而不是 PATH 解析的 claude，以便解碼在執行者本身使用的相同二進位檔案上執行。

使用 jq -re 而不是 jq -r，以便遺漏的聲明導致非零退出。僅使用 -r，遺漏的聲明會列印字面字串 null 並以零退出，這會無聲地將壞值傳遞到下游。僅當 JWKS 端點無法到達的離線檢查時，才將 --no-verify 傳遞給 decode-token。

聲明參考

下表列出了與驗證相關的工作階段令牌聲明。從 ccr:* 命名空間和 act 鏈讀取身份；平面 account_email、organization_uuid 和 account_uuid 聲明是可能被移除的向後相容性重複項。您組織的服務身份建立的工作階段（包括 Claude Tag 頻道工作階段）在 act.sub 中帶有 agent: 主體，並省略 act.email、ccr:account_id、account_email 和 account_uuid。兩個電子郵件聲明對於使用者建立的工作階段也是可選的：Anthropic 僅在建立請求的認證帶有電子郵件時才在工作階段建立時記錄它們，從 CLI 分派的工作階段可能兩者都缺少，因此根據 act.sub 或 ccr:account_id 而不是電子郵件來識別身份。令牌也可以帶有超出此表的其他聲明；忽略您不認識的聲明。

The `act` chain

act 聲明記錄了從建立工作階段的使用者或服務身份到環境（其祕密允許執行者）以及建立該祕密的身份的完整委派路徑。建立者是最外層的參與者，因此 act.sub 直接識別他們。

範圍衍生認證

工作階段令牌識別建立工作階段的使用者或服務身份，但不要將其視為等同於該建立者直接登入。令牌位於工作階段內的環境變數中，因此 Claude 執行的任何程式碼以及工作階段啟動的任何工具或 MCP 伺服器都可以讀取並呈現它。

驗證也是離線的：根據 JWKS 驗證的令牌在其 exp 之前保持有效，無論自那時以來工作階段發生了什麼，Anthropic 不會為工作階段令牌發佈撤銷源。相應地綁定您從令牌衍生的任何內容。

當您的服務將令牌交換為內部認證時，簽發範圍限制在一個編碼工作階段應該到達的內容的認證：

• 限制功能：授予工作階段編碼任務所需的資源的讀取和寫入存取權限，而不是建立者在其他地方持有的管理功能。
• 限制生命週期：將衍生認證綁定到令牌的 exp 或更短。
• 作為工作階段進行審計：記錄 ccr:session_id 和 jti 以及建立者身份，以便您可以將操作追蹤回特定工作階段。

相關環境變數

建立者身份也以純環境變數的形式出現在兩個永遠不驗證令牌的表面上：

• spawn-runner hook，在協調器上：hook 在任何執行者存在於佇列工作階段之前執行，並在 CLAUDE_RUNNER_ACCOUNT_EMAIL 和 CLAUDE_RUNNER_ACCOUNT_ID 等變數中接收建立者身份。協調器從工作訂單（授權生成一個執行者的簽署單次使用令牌）讀取它們，而不驗證工作訂單的簽名本身；聲明是受信任的，因為工作訂單通過協調器與 Anthropic 的連線到達，環境祕密對其進行驗證。
• 包裝指令碼，在工作階段內：包裝器接收 CCR_SESSION_ACCOUNT_EMAIL，建立者的電子郵件從令牌預先提取，無需簽名驗證。該變數適合用於標籤，例如提交預告片，而不是用於驗證決定。

使用純變數進行協調器端決定，例如選擇機器映像。當下游服務需要獨立的密碼學證明而不是信任執行者的環境時，使用 CLAUDE_CODE_SESSION_ACCESS_TOKEN。

接下來

• 自託管環境：環境、執行者和工作階段模型；快速入門和部署到生產環境包含設定和操作
• 自訂工作階段：使用令牌的包裝指令碼，以及 spawn-runner hook
• 參考：CLI 旗標、環境變數和指標