Workload Identity Federation

"Workload Identity Federation" (federação de identidade de workload), ou WIF, permite que seus workloads se autentiquem na API do Claude com tokens OpenID Connect (OIDC) de curta duração em vez de chaves de API sk-ant-... de longa duração. Os tokens vêm de um "identity provider" (provedor de identidade), ou IdP, que você já opera: AWS IAM, Google Cloud ou qualquer emissor OIDC em conformidade com os padrões, como GitHub Actions, Kubernetes, SPIFFE, Microsoft Entra ID ou Okta.

Seu workload apresenta um JWT assinado pelo seu provedor de identidade. A Anthropic o valida em relação às regras de confiança que você configura no Claude Console e retorna um token de acesso da Anthropic de curta duração vinculado a uma conta de serviço na sua organização. Não há segredos estáticos para gerar, armazenar em CI, rotacionar ou vazar.

O Workload Identity Federation fortalece sua postura de segurança ao substituir chaves de API estáticas por tokens que expiram em minutos em vez de nunca. Ele não é uma solução de segurança completa por si só: a autenticação federada é tão forte quanto o provedor de identidade upstream que assina o JWT. Combine o Workload Identity Federation com os controles que seu IdP já oferece (vinculação de identidade de workload, acesso condicional, registro de auditoria) para defesa em profundidade.

Conceitos

Você configura três recursos no Claude Console antes que qualquer workload possa federar. Juntos, eles expressam "tokens assinados pelo emissor X, com claims que se parecem com Y, podem atuar como a conta de serviço Z."

Contas de serviço

Uma conta de serviço (svac_...) é uma identidade nomeada e não humana dentro da sua organização na Anthropic. É o principal em nome do qual um token federado atua. Contas de serviço existem no nível da organização e tornam-se ativas em um workspace quando você as adiciona como membros desse workspace. No momento da troca, a Anthropic verifica se o workspace da regra de federação corresponde a uma das associações de workspace da conta de serviço; o token gerado então segue os limites de taxa e a atribuição de uso desse workspace, da mesma forma que uma chave de API. Diferentemente de um usuário humano, uma conta de serviço não tem e-mail, senha nem login no Console.

A distinção principal em relação a uma chave de API: uma chave de API é uma credencial, enquanto uma conta de serviço tem credenciais geradas para ela sob demanda. Você pode auditar quais workloads atuaram como qual conta de serviço.

Emissores de federação

Um emissor de federação (fdis_...) registra um provedor de identidade OIDC na sua organização. Registrar um emissor informa à Anthropic que "JWTs assinados por este provedor podem declarar identidade de workload para minha organização."

Um emissor tem duas partes de configuração:

• URL do emissor: O valor exato do claim iss que aparece nos JWTs do provedor, por exemplo https://token.actions.githubusercontent.com ou https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLE.
• Fonte JWKS: Como a Anthropic obtém as chaves públicas para verificar assinaturas de JWT. Use discovery (o padrão) para qualquer provedor que sirva /.well-known/openid-configuration na sua URL de emissor. Use explicit_url para apontar diretamente para um endpoint JWKS, ou inline para fazer upload do conjunto de chaves para emissores que não são acessíveis pela internet pública (por exemplo, um cluster Kubernetes privado).

URLs de emissor e JWKS devem ser https, na porta 443, e usar um nome de host DNS público que resolva para endereços IP públicos; literais de IP não são aceitos. Essas restrições se aplicam apenas a URLs que a Anthropic busca; nos modos explicit_url e inline, a issuer_url é comparada como uma string e pode referenciar um hostname interno.

Normalmente você registra um emissor por ambiente: seu cluster EKS de produção, seu cluster de staging e o GitHub Actions são três emissores separados.

Regras de federação

Uma regra de federação (fdrl_...) é a ponte entre um emissor e uma conta de serviço: "quando um JWT do emissor X tiver claims que se parecem com Y, gere um token para a conta de serviço Z com escopo S."

Uma regra define condições de correspondência, um alvo, e o escopo de autorização e tempo de vida do token que se aplicam quando a regra corresponde:

• Match: As condições que um JWT recebido deve satisfazer. Você pode corresponder com base em um subject_prefix (por exemplo, system:serviceaccount:prod:worker, ou com um * no final para correspondência de prefixo), um audience exato, um mapa de valores exatos de claims, uma expressão condition em CEL para lógica complexa, ou qualquer combinação. Pelo menos um entre subject_prefix, claims ou condition deve ser definido, e todos os matchers configurados devem passar para que o JWT seja aceito.
• Target: A conta de serviço para a qual o JWT correspondente é mapeado.
• Authorization: O scope OAuth concedido no token gerado. O padrão é workspace:developer, que concede o mesmo acesso que uma chave de API emitida para esse workspace. Alguns produtos fixam o escopo quando você cria uma regra a partir do fluxo deles; por exemplo, o modal de criação de túnel dos túneis MCP cria regras com escopo org:manage_tunnels. Consulte Escopos OAuth. A regra também define token_lifetime_seconds (60 a 86400, padrão 3600).

Um único emissor pode ter muitas regras: uma por equipe, namespace ou nível de permissão. As regras são avaliadas por ID: o cliente especifica qual regra usar na requisição de troca, e a Anthropic verifica se o JWT satisfaz os critérios de correspondência dessa regra. Não há busca implícita de regras.

Como funciona

1. Seu IdP emite um JWT para o workload. Na maioria das plataformas isso é ambiente: um token de conta de serviço projetado do Kubernetes, o servidor de metadados do Google Cloud, o Azure IMDS ou o endpoint OIDC do GitHub Actions. O claim iss do JWT identifica o provedor, e seu sub e outros claims identificam o workload específico.
2. O SDK troca o JWT por um token de acesso da Anthropic. O SDK envia o JWT via POST para POST /v1/oauth/token usando o grant jwt-bearer do RFC 7523. A Anthropic verifica o JWT em relação ao JWKS do emissor e às condições de correspondência da regra de federação, e então retorna um token sk-ant-oat01-... de curta duração que atua em nome da conta de serviço alvo da regra.
3. O SDK envia o token em cada requisição e o renova antes que expire. O código da sua aplicação constrói o cliente sem api_key e chama a API normalmente. O SDK executa novamente a troca antes que o token expire.

Configurar a federação

Você precisa de acesso de administrador à sua organização na Anthropic, um provedor de identidade compatível com OIDC com um endpoint JWKS acessível (ou um documento JWKS que você possa colar, para clusters isolados), e um workload que possa obter um token de identidade desse provedor.

No Claude Console, vá para Settings → Workload identity.

Autenticar a partir do seu workload

Com a federação configurada, seu workload troca seu JWT emitido pelo IdP por um token da Anthropic em tempo de execução. Os SDKs cuidam do loop de troca e renovação para você. A aba cURL mostra a troca HTTP subjacente para scripts shell, depuração ou linguagens sem suporte de SDK.

Construir o cliente do SDK

Você pode construir o cliente com credenciais explícitas ou sem argumentos. Sem argumentos, o SDK resolve credenciais a partir de variáveis de ambiente ou do perfil ativo, conforme descrito em Precedência de credenciais. A forma sem argumentos é o padrão recomendado para workloads de produção: distribua a mesma imagem de container em todos os lugares e injete ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID, ANTHROPIC_WORKSPACE_ID e ANTHROPIC_IDENTITY_TOKEN_FILE por ambiente.

from anthropic import Anthropic, WorkloadIdentityCredentials, IdentityTokenFile

client = Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=IdentityTokenFile(
            "/var/run/secrets/anthropic.com/token"
        ),
        federation_rule_id="fdrl_...",
        organization_id="00000000-0000-0000-0000-000000000000",
        service_account_id="svac_...",
        workspace_id="wrkspc_...",
    ),
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].text)

A resposta da troca de token segue o RFC 6749 §5.1. Consulte Resposta da troca de token para a referência de campos.

Precedência de credenciais

Todo SDK resolve credenciais na mesma ordem de cinco níveis: argumentos do construtor, depois ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN, depois um ANTHROPIC_PROFILE explícito, depois as variáveis de ambiente de federação, depois o perfil ativo implícito. A primeira fonte que produzir uma credencial vence.

Para a tabela completa de precedência, a semântica de cada nível e o esquema do arquivo de perfil, consulte Precedência de credenciais na referência do WIF.

Migrar de chaves de API

Para mudar um workload existente de uma chave de API estática para federação sem tempo de inatividade:

1. Configure a federação em paralelo. Conclua o passo a passo de configuração e confirme que a regra de federação corresponde ao token do seu workload. Deixe a ANTHROPIC_API_KEY existente no lugar por enquanto.
2. Faça um smoke test de qual credencial vence. Execute ant auth status de dentro do workload (ou inspecione os logs de debug do SDK). Como ANTHROPIC_API_KEY fica acima dos níveis de federação na cadeia de precedência, a chave de API ainda vence nesta etapa.
3. Remova ANTHROPIC_API_KEY de todos os lugares onde ela é injetada. Remova-a dos segredos de CI, do ambiente do container e dos perfis de shell (veja o aviso anterior). Execute novamente ant auth status e confirme que a fonte de federação agora está selecionada.
4. Revogue a chave de API. Assim que o workload estiver rodando com o token federado, exclua a chave no Claude Console em Settings → API keys.

Tempo de vida e renovação do token

O tempo de vida do token da Anthropic gerado é o menor entre (a) o token_lifetime_seconds da regra (padrão 3600 segundos) e (b) o dobro do tempo de vida restante do JWT do IdP que você apresentou. O resultado nunca é menor que 60 segundos. O segundo limite impede que um token da Anthropic sobreviva à identidade upstream da qual foi derivado por mais do que uma pequena margem.

Os SDKs armazenam o token em cache e o renovam em um cronograma de dois níveis modelado no botocore:

• Renovação consultiva na expiração menos 120 segundos. O SDK tenta uma nova troca. Se o endpoint de token estiver inacessível, o SDK continua servindo o token em cache, que ainda é válido por aproximadamente mais 90 segundos.
• Renovação obrigatória na expiração menos 30 segundos. Uma troca com falha neste ponto gera um erro. O token em cache está próximo demais da expiração para ser seguro.

Como o SDK relê ANTHROPIC_IDENTITY_TOKEN_FILE em cada troca, ele captura de forma transparente tokens projetados rotacionados (tokens de conta de serviço do Kubernetes, por exemplo, são rotacionados bem antes do seu exp).

Provedores de identidade

Cada guia aborda de onde vem o JWT naquela plataforma, como são seus claims, e a configuração de emissor e regra a registrar.

Veja também

• Referência do WIF: variáveis de ambiente, esquema do arquivo de perfil, regras de validação e códigos de erro
• Autenticação: todas as opções de autenticação nos SDKs da Anthropic