Verificare l'identità della sessione negli ambienti self-hosted

​

Il token della sessione

​

Cosa prova il token

• Prova: Anthropic ha emesso il token per una sessione specifica in un ambiente specifico e come è stata creata la sessione: da un utente nella vostra organizzazione, o dall’identità del servizio della vostra organizzazione, che è come iniziano le sessioni del canale Claude Tag
• Non prova: quale processo sull’host del runner lo presenta. Il token si trova in una variabile di ambiente all’interno della sessione, quindi qualsiasi codice che Claude esegue e qualsiasi tool o server MCP che la sessione avvia può leggerlo e presentarlo.

• Verificate il claim aud rispetto all’ID del vostro ambiente, il valore ccpool_... mostrato con il vostro ambiente nella pagina di amministrazione Cloud environments, per rifiutare i token emessi per l’ambiente di qualsiasi altra organizzazione.
• Limitate le credenziali che derivate dal token a quello che una singola sessione di codifica dovrebbe essere in grado di fare, non a tutto quello che il creatore della sessione può fare. Consultare Scope derived credentials.

​

Formato del token

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

​

Verificare il token

​

Verificare il token dal vostro servizio

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

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"),
    }

​

Verificare il token all’interno della sessione

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

​

Riferimento dei claim

​

La catena act

​

Scope derived credentials

• Limitate le capacità: concedete accesso in lettura e scrittura alle risorse di cui la sessione ha bisogno per i compiti di codifica, non alle capacità amministrative che il creatore detiene altrove.
• Limitate la durata: limitate le credenziali derivate al exp del token, o più breve.
• Controllate come la sessione: registrate ccr:session_id e jti insieme all’identità del creatore in modo da poter tracciare le azioni di nuovo a una sessione specifica.

​

Variabili di ambiente correlate

• L’hook spawn-runner, sull’orchestratore: l’hook viene eseguito prima che esista un runner per una sessione in coda e riceve l’identità del creatore in variabili come CLAUDE_RUNNER_ACCOUNT_EMAIL e CLAUDE_RUNNER_ACCOUNT_ID. L’orchestratore le legge dall’ordine di lavoro, il token firmato monouso che autorizza l’avvio di un runner, senza verificare la firma dell’ordine di lavoro stesso; i claim sono attendibili perché l’ordine di lavoro arriva sulla connessione dell’orchestratore ad Anthropic, che il segreto dell’ambiente autentica.
• Script wrapper, all’interno della sessione: i wrapper ricevono CCR_SESSION_ACCOUNT_EMAIL, l’email del creatore pre-estratta dal token senza verifica della firma. La variabile è adatta per l’etichettatura, come i trailer di commit, non per le decisioni di autenticazione.

​

Cosa c’è dopo

• Self-hosted environments: l’ambiente, il runner e il modello di sessione; la guida rapida e Deploy to production contengono la configurazione e le operazioni
• Customize sessions: script wrapper che consumano il token e l’hook spawn-runner
• Reference: flag CLI, variabili di ambiente e metriche