Workload Identity Federation

O "Workload Identity Federation" (federação de identidade de workload), ou WIF, permite que seus workloads se autentiquem na Claude API 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 provedor de identidade (IdP) que você já opera: AWS IAM, Google Cloud, ou qualquer emissor OIDC compatível 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 contra regras de confiança que você configura no Claude Console e retorna um token de acesso Anthropic de curta duração vinculado a uma conta de serviço na sua organização. Não há segredos estáticos para criar, 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. Não é uma história 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á suporta (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 Anthropic. É o principal como o qual um token federado atua. As contas de serviço existem no nível da organização e se tornam 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 emitido 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. Toda conta de serviço é implicitamente membro do workspace padrão da sua organização; adicione associações explícitas para qualquer outro workspace em que ela deva atuar.

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 emitidas 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 diz à Anthropic "JWTs assinados por este provedor podem afirmar identidade de workload para minha organização."

Um emissor tem duas partes de configuração:

• URL do emissor: O valor exato da 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 busca as chaves públicas para verificar as assinaturas dos JWTs. 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).

As URLs do emissor e do JWKS devem ser https, na porta 443, e usar um hostname 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 às URLs que a Anthropic busca; nos modos explicit_url e inline, a issuer_url é comparada como uma string e pode referenciar um hostname interno.

Você normalmente 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 tem claims que se parecem com Y, emita 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 o tempo de vida do token que se aplicam quando a regra corresponde:

• Correspondência: As condições que um JWT de entrada deve satisfazer. Você pode fazer correspondência em um subject_prefix (por exemplo, system:serviceaccount:prod:worker, ou com um * no final para uma correspondência de prefixo), uma audience exata, 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.
• Alvo: A conta de serviço à qual o JWT correspondido é mapeado.
• Autorização: O scope OAuth concedido no token emitido. O padrão é workspace:developer, que concede o mesmo acesso que uma chave de API emitida para aquele workspace. Alguns produtos travam 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 workspace: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. A claim iss do JWT identifica o provedor, e suas claims sub e outras identificam o workload específico.
2. O SDK troca o JWT por um token de acesso 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 contra o JWKS do emissor e as 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. Seu código de 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 do papel de admin, owner ou primary owner na sua organização Anthropic, de um provedor de identidade com capacidade OIDC com um endpoint JWKS acessível (ou um documento JWKS que você possa colar, para clusters isolados da internet), e de um workload que possa obter um token de identidade desse provedor.

O assistente Connect workload cria os três recursos (o emissor, a conta de serviço e a regra de federação) em um único fluxo guiado, e então verifica a conexão de ponta a ponta.

Para gerenciar esses recursos programaticamente, consulte Gerenciar WIF com a Admin API para o passo a passo com curl, ou consulte a referência da API de contas de serviço, a referência da API de emissores de federação e a referência da API de regras de federação para detalhes completos de parâmetros e esquemas de resposta.



Autenticar a partir do seu workload

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



Construa o cliente do SDK

Você pode construir o cliente com credenciais explícitas ou sem argumentos. Sem argumentos, o SDK resolve as 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 contêiner 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-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(next(block.text for block in message.content if block.type == "text"))

A resposta da troca de token segue o RFC 6749 §5.1. Consulte Resposta da troca de token para a referência dos 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 produz 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 trocar um workload existente de uma chave de API estática para federação sem tempo de inatividade:

1. Configure a federação em paralelo. Complete 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 teste rápido de qual credencial vence. Execute ant auth status de dentro do workload (ou inspecione os logs de depuração 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 contêiner e dos perfis de shell (veja o aviso anterior). Execute ant auth status novamente 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 Anthropic emitido é o menor entre (a) o token_lifetime_seconds da regra (padrão de 3.600 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 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 que falhe 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 cobre de onde vem o JWT naquela plataforma, como são suas claims, e a configuração de emissor e regra a registrar.



Veja também

• Gerenciar WIF com a Admin API: crie emissores, contas de serviço e regras a partir de infraestrutura como código
• 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
• Referência da Admin API: esquemas gerados de requisição e resposta para cada endpoint da Admin API