Vérifier l'identité de session dans les environnements auto-hébergés

​

Le token de session

​

Ce que le token prouve

• Prouve : Anthropic a émis le token pour une session spécifique dans un environnement spécifique, et comment la session a été créée : par un utilisateur de votre organisation, ou par l’identité de service de votre organisation, ce qui est la façon dont les sessions de canal Claude Tag commencent
• Ne prouve pas : quel processus sur l’hôte du runner le présente. Le token se trouve dans une variable d’environnement à l’intérieur de la session, donc tout code que Claude exécute, et tout outil ou serveur MCP que la session démarre, peut le lire et le présenter.

• Vérifiez le claim aud par rapport à votre ID d’environnement, la valeur ccpool_... affichée avec votre environnement sur la page d’administration Cloud environments, pour rejeter les tokens émis pour l’environnement de toute autre organisation.
• Limitez les credentials que vous dérivez du token à ce qu’une seule session de codage devrait pouvoir faire, pas à tout ce que le créateur de la session peut faire. Voir Limiter les credentials dérivés.

​

Format du token

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

​

Vérifier le token

​

Vérifier le token depuis votre service

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

​

Vérifier le token à l’intérieur de la session

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

​

Référence des claims

​

La chaîne act

​

Limiter les credentials dérivés

• Limiter les capacités : accordez l’accès en lecture et en écriture aux ressources dont la session a besoin pour les tâches de codage, pas aux capacités administratives que le créateur détient ailleurs.
• Limiter la durée de vie : limitez les credentials dérivés à l’exp du token, ou moins.
• Auditer en tant que session : enregistrez le ccr:session_id et le jti aux côtés de l’identité du créateur afin de pouvoir retracer les actions jusqu’à une session spécifique.

​

Variables d’environnement associées

• Le hook spawn-runner, sur l’orchestrateur : le hook s’exécute avant que tout runner n’existe pour une session en attente et reçoit l’identité du créateur dans des variables telles que CLAUDE_RUNNER_ACCOUNT_EMAIL et CLAUDE_RUNNER_ACCOUNT_ID. L’orchestrateur les lit à partir de l’ordre de travail, le token à usage unique signé qui autorise le spawning d’un runner, sans vérifier la signature de l’ordre de travail lui-même ; les claims sont de confiance car l’ordre de travail arrive sur la connexion de l’orchestrateur à Anthropic, que le secret d’environnement authentifie.
• Scripts wrapper, à l’intérieur de la session : les wrappers reçoivent CCR_SESSION_ACCOUNT_EMAIL, l’e-mail du créateur pré-extrait du token sans vérification de signature. La variable convient pour l’étiquetage, tel que les remorques de commit, pas pour les décisions d’authentification.

​

Prochaines étapes

• Environnements auto-hébergés : l’environnement, le runner et le modèle de session ; le guide de démarrage rapide et Déployer en production contiennent la configuration et les opérations
• Personnaliser les sessions : les scripts wrapper qui consomment le token, et le hook spawn-runner
• Référence : les drapeaux CLI, les variables d’environnement et les métriques