Verificar identidade de sessão em ambientes auto-hospedados

​

O token de sessão

​

O que o token prova

• Prova: Anthropic emitiu o token para uma sessão específica em um ambiente específico, e como a sessão foi criada: por um usuário em sua organização, ou pela identidade de serviço de sua organização, que é como sessões de canal Claude Tag começam
• Não prova: qual processo no host do runner o apresenta. O token fica em uma variável de ambiente dentro da sessão, portanto qualquer código que Claude executa e qualquer ferramenta ou servidor MCP que a sessão inicia pode lê-lo e apresentá-lo.

• Verifique a declaração aud contra seu ID de ambiente, o valor ccpool_... mostrado com seu ambiente na página de administração Cloud environments, para rejeitar tokens emitidos para o ambiente de qualquer outra organização.
• Escope as credenciais que você deriva do token para o que uma única sessão de codificação deve ser capaz de fazer, não para tudo que o criador da sessão pode fazer. Consulte Escopo de credenciais derivadas.

​

Formato do token

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

​

Verificar o token

​

Verificar o token de seu serviço

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 o token dentro da sessão

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

​

Referência de declarações

​

A cadeia act

​

Escopo de credenciais derivadas

• Limitar capacidades: conceda acesso de leitura e escrita aos recursos que a sessão precisa para tarefas de codificação, não às capacidades administrativas que o criador possui em outro lugar.
• Limitar tempo de vida: vincule credenciais derivadas ao exp do token, ou mais curto.
• Auditar como a sessão: registre ccr:session_id e jti junto com a identidade do criador para que você possa rastrear ações de volta a uma sessão específica.

​

Variáveis de ambiente relacionadas

• O hook spawn-runner, no orquestrador: o hook é executado antes de qualquer runner existir para uma sessão enfileirada e recebe a identidade do criador em variáveis como CLAUDE_RUNNER_ACCOUNT_EMAIL e CLAUDE_RUNNER_ACCOUNT_ID. O orquestrador as lê da ordem de trabalho, o token de uso único assinado que autoriza a geração de um runner, sem verificar a assinatura da ordem de trabalho em si; as declarações são confiáveis porque a ordem de trabalho chega pela conexão do orquestrador com Anthropic, que o segredo do ambiente autentica.
• Scripts de wrapper, dentro da sessão: wrappers recebem CCR_SESSION_ACCOUNT_EMAIL, o email do criador pré-extraído do token sem verificação de assinatura. A variável é adequada para rotulagem, como trailers de commit, não para decisões de autenticação.

​

Próximas etapas

• Ambientes auto-hospedados: o ambiente, runner e modelo de sessão; o quickstart e Deploy to production contêm configuração e operações
• Personalizar sessões: scripts de wrapper que consomem o token e o hook spawn-runner
• Referência: sinalizadores CLI, variáveis de ambiente e métricas