Verificar la identidad de la sesión en entornos autohospedados

​

El token de sesión

​

Qué prueba el token

• Prueba: Anthropic emitió el token para una sesión específica en un entorno específico, y cómo se creó la sesión: por un usuario en su organización, o por la identidad de servicio de su organización, que es cómo comienzan las sesiones del canal Claude Tag
• No prueba: qué proceso en el host del ejecutor lo presenta. El token se encuentra en una variable de entorno dentro de la sesión, por lo que cualquier código que Claude ejecute y cualquier herramienta o servidor MCP que inicie la sesión puede leerlo y presentarlo.

• Verifique la reclamación aud contra su ID de entorno, el valor ccpool_... que se muestra con su entorno en la página de administración Cloud environments, para rechazar tokens emitidos a cualquier entorno de otra organización.
• Limite las credenciales que derive del token a lo que una única sesión de codificación debería poder hacer, no a todo lo que el creador de la sesión puede hacer. Consulte Limitar credenciales derivadas.

​

Formato del token

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

​

Verificar el token

​

Verificar el token desde su servicio

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

​

Verificar el token dentro de la sesión

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

​

Referencia de reclamaciones

​

La cadena act

​

Limitar credenciales derivadas

• Limitar capacidades: otorgue acceso de lectura y escritura a los recursos que la sesión necesita para tareas de codificación, no a las capacidades administrativas que el creador tiene en otros lugares.
• Limitar vida útil: limite las credenciales derivadas a exp del token, o menos.
• Auditar como la sesión: registre ccr:session_id y jti junto con la identidad del creador para que pueda rastrear acciones hasta una sesión específica.

​

Variables de entorno relacionadas

• El hook spawn-runner, en el orquestador: el hook se ejecuta antes de que exista cualquier ejecutor para una sesión en cola y recibe la identidad del creador en variables como CLAUDE_RUNNER_ACCOUNT_EMAIL y CLAUDE_RUNNER_ACCOUNT_ID. El orquestador las lee de la orden de trabajo, el token de un solo uso firmado que autoriza generar un ejecutor, sin verificar la firma de la orden de trabajo en sí; las reclamaciones se confían porque la orden de trabajo llega sobre la conexión del orquestador a Anthropic, que el secreto del entorno autentica.
• Scripts contenedores, dentro de la sesión: los contenedores reciben CCR_SESSION_ACCOUNT_EMAIL, el correo electrónico del creador preextraído del token sin verificación de firma. La variable es adecuada para etiquetado, como remolques de confirmación, no para decisiones de autenticación.

​

Qué sigue

• Entornos autohospedados: el modelo de entorno, ejecutor y sesión; el inicio rápido y Implementar en producción contienen configuración y operaciones
• Personalizar sesiones: scripts contenedores que consumen el token y el hook spawn-runner
• Referencia: banderas CLI, variables de entorno y métricas