Workload Identity Federation

"Workload Identity Federation" (federação de identidade de carga de trabalho), ou WIF, permite que suas cargas de trabalho 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 "identity provider" (provedor de identidade), ou 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.

Sua carga de trabalho 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 emitir, 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á suporta (vinculação de identidade de carga de trabalho, acesso condicional, registro de auditoria) para defesa em profundidade.

Conceitos

Você configura três recursos no Claude Console antes que qualquer carga de trabalho 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 "service account" (conta de serviço) (svac_...) é uma identidade nomeada e não humana dentro da sua organização Anthropic. É o principal como o qual uma chave de conta de serviço ou 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. Para permitir que uma chave de conta de serviço de todos os workspaces atue em um workspace, adicione a conta de serviço a esse workspace.

A distinção principal em relação a uma chave de API de workspace: uma chave de API de workspace é uma credencial, enquanto uma conta de serviço tem credenciais. Você pode auditar com mais facilidade quais cargas de trabalho atuaram como qual conta de serviço.

Emissores de federação

Um "federation issuer" (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 carga de trabalho 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 de emissor e de 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 às URLs que a Anthropic busca; nos modos explicit_url e inline, a issuer_url é comparada como uma string e pode referenciar um nome de host 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 "federation rule" (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 o 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 recebido deve satisfazer. Você pode corresponder por 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 para a qual o JWT correspondente é 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 de workspace. Alguns produtos bloqueiam 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 solicitaçã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 a carga de trabalho. 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 sua sub e outras claims identificam a carga de trabalho específica.
2. O SDK troca o JWT por um token de acesso da Anthropic. O SDK envia o JWT para POST /v1/oauth/token usando o grant jwt-bearer da 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 solicitaçã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 da função de admin, owner ou primary owner na sua organização Anthropic, de 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 da rede) e de uma carga de trabalho que possa obter um token de identidade desse provedor.

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

1. 1

   Abra Connect workload

   No Claude Console, vá para Settings → Workload identity e selecione Connect workload.

2. 2

   Escolha seu provedor

   Selecione o bloco do seu provedor de identidade: GitHub Actions, AWS, Google Cloud, Microsoft Entra ID ou Kubernetes. Cada bloco preenche previamente o padrão de URL do emissor e os campos de correspondência que os JWTs desse provedor suportam. Para qualquer outro provedor compatível com os padrões (como SPIFFE ou Okta), selecione Custom OIDC.

3. 3

   Preencha os campos guiados

   O assistente conduz você pelos campos específicos do provedor: a configuração do emissor, as condições de correspondência para JWTs recebidos e os nomes da conta de serviço e da regra de federação que ele cria. O assistente preenche previamente oauth_scope=workspace:developer e token_lifetime_seconds=600 (o padrão da API quando token_lifetime_seconds é omitido é 3600); ajuste esses valores se sua carga de trabalho precisar de um escopo ou tempo de vida diferente.

4. 4

   Verifique o emissor

   Opcionalmente, selecione Verify issuer para fazer um teste da configuração do emissor antes que qualquer coisa seja criada. A verificação confirma que a Anthropic consegue buscar e analisar o JWKS a partir das URLs que você inseriu, o que detecta erros de acessibilidade e configuração antecipadamente.

5. 5

   Teste a conexão

   O assistente cria o emissor, a conta de serviço e a regra de federação e, em seguida, aguarda uma troca de token bem-sucedida por 15 minutos. Dispare uma troca a partir da sua carga de trabalho dentro dessa janela (consulte Autenticar a partir da sua carga de trabalho) para confirmar que a configuração funciona. Se a janela expirar, os recursos persistem; você pode executar o teste novamente na página de detalhes da regra de federação. Anote o ID da regra (fdrl_...) e o ID da conta de serviço (svac_...) que o assistente cria: sua carga de trabalho passa ambos, junto com o ID da sua organização (e o ID do seu workspace quando a regra abrange mais de um workspace), em cada solicitação de troca de token.

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 da sua carga de trabalho

Com a federação configurada, sua carga de trabalho troca seu JWT emitido pelo IdP por um token da Anthropic em tempo de execução. Os SDKs cuidam da troca e do 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.

Construir 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 cargas de trabalho 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 a 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 e, por fim, o perfil ativo implícito. A primeira fonte que fornecer 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 uma carga de trabalho 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 da sua carga de trabalho. 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 da carga de trabalho (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 (consulte o aviso anterior). Execute ant auth status novamente e confirme que a fonte de federação agora está selecionada.
4. Exclua a chave de API. Quando a carga de trabalho 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 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 é inferior a 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 recomendada 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á muito próximo 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, rotacionam bem antes do seu exp).

Por padrão, tokens de identidade que carregam uma claim jti são de uso único: cada troca deve apresentar um JWT que não tenha sido trocado antes, e reapresentar um falha com o motivo jti_reused na página de histórico de autenticação. Se sua carga de trabalho busca seus próprios tokens do seu provedor de identidade, emita um JWT novo para cada troca em vez de reutilizar um em cache (loops de retentativa são o culpado comum). O mesmo se aplica a um token lido de ANTHROPIC_IDENTITY_TOKEN_FILE: o SDK relê o arquivo em cada troca, portanto o arquivo deve conter um novo token antes de cada renovação. Uma renovação que relê um token não rotacionado, ou um processo reiniciado que reapresenta um token que já trocou, é rejeitada da mesma forma. Rotacionar o token bem dentro do tempo de vida do token emitido mantém o arquivo à frente do cronograma de renovação; se sua fonte de tokens não puder rotacionar com essa frequência, você pode desabilitar check_jti para esse emissor como último recurso (isso remove a proteção contra replay para todas as regras do emissor). Consulte Verificação de JWT para detalhes.

Provedores de identidade

Cada guia aborda de onde vem o JWT nessa 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 de solicitação e resposta gerados para cada endpoint da Admin API