Referência do WIF

Esta página reúne as superfícies de configuração, restrições de validação e mapeamentos de erros para Workload Identity Federation. Para passo a passo de configuração, consulte os guias de provedores.

Requisição de troca de token

POST /v1/oauth/token aceita um corpo JSON usando o grant jwt-bearer da RFC 7523. Os SDKs constroem essa requisição para você a partir das variáveis de ambiente; os exemplos de cURL em cada guia de provedor mostram o corpo bruto.

Resposta da troca de token

POST /v1/oauth/token retorna uma resposta de token OAuth 2.0 padrão (RFC 6749 §5.1):

Variáveis de ambiente

O SDK lê essas variáveis para realizar uma troca de token federada sem argumentos de construtor.

O caminho de federação direto por variáveis de ambiente é ativado somente quando ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID e uma entre ANTHROPIC_IDENTITY_TOKEN_FILE ou ANTHROPIC_IDENTITY_TOKEN estão todas definidas. ANTHROPIC_WORKSPACE_ID é lida junto, mas não condiciona a ativação.

Precedência de credenciais

O SDK resolve credenciais nesta ordem. A primeira fonte que produzir uma credencial vence.

Quando um perfil é carregado, as variáveis de ambiente preenchem quaisquer campos que o perfil omite, mas nunca sobrepõem campos que o perfil define explicitamente. Por exemplo, ANTHROPIC_WORKSPACE_ID preenche workspace_id somente quando o perfil ativo não o define.

Arquivo de configuração de perfil

Um perfil é um arquivo de configuração nomeado que tanto o SDK quanto a CLI ant leem. Perfis permitem que você distribua parâmetros de federação com sua imagem de contêiner ou alterne entre ambientes sem alterar código.

Diretório de configuração

O SDK localiza o diretório de configuração nesta ordem:

1. $ANTHROPIC_CONFIG_DIR
2. ~/.config/anthropic no Linux e macOS
3. %APPDATA%\Anthropic no Windows

Perfil ativo

O nome do perfil ativo é resolvido nesta ordem:

1. $ANTHROPIC_PROFILE
2. O conteúdo de <config_dir>/active_config (um arquivo de uma linha escrito por ant profile activate <name>)
3. O nome literal default

O Claude Code e o Claude Agent SDK respeitam essa mesma ordem de resolução, portanto um perfil de federação configurado aqui também autentica essas ferramentas sem configuração adicional.

Layout de arquivos

Tanto o arquivo de configuração quanto o arquivo de credenciais carregam um campo string version de nível superior no formato major.minor (atualmente "1.0"). O SDK escreve esse campo automaticamente para que versões futuras possam detectar e migrar formatos mais antigos; omita-o ao criar uma configuração manualmente e o SDK tratará o arquivo como a versão atual.

Exemplo de perfil de federação

{
  "version": "1.0",
  "authentication": {
    "type": "oidc_federation",
    "federation_rule_id": "fdrl_...",
    "service_account_id": "svac_...",
    "identity_token": {
      "source": "file",
      "path": "/var/run/secrets/anthropic.com/token"
    }
  },
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "wrkspc_...",
  "base_url": "https://api.anthropic.com"
}

Se authentication.identity_token for omitido, o SDK recorre a ANTHROPIC_IDENTITY_TOKEN_FILE ou ANTHROPIC_IDENTITY_TOKEN do ambiente.

Escopos OAuth

O oauth_scope que você define em uma regra de federação determina quais endpoints da Claude API o token de acesso emitido pode chamar.

Uma requisição a um endpoint fora do escopo do token retorna HTTP 403. Escopos mais granulares (por recurso, ou leitura versus escrita) não estão disponíveis atualmente.

Limites de permissão

O oauth_scope de uma regra de federação é um teto: o token emitido nunca pode excedê-lo. O organization_role da conta de serviço de destino (developer ou admin) determina quais escopos podem ser concedidos, portanto uma regra que concede org:admin deve ter como destino uma conta de serviço com organization_role=admin. As permissões efetivas são a interseção do escopo da regra e da função da conta de serviço.

Regras de validação

A Anthropic aplica essas restrições quando você cria ou atualiza emissores e regras, e ao verificar um JWT recebido no momento da troca.

Para detalhes completos de parâmetros e esquemas de resposta, 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.

Campos de recurso

Campos de URL

Os campos issuer_url, jwks.discovery_base e jwks.url são validados:

Falhas de validação de URL retornam 400 invalid_request_error com o nome do campo como prefixo na mensagem de erro (por exemplo, issuer_url: url must use https scheme).

Verificação de JWT

Semântica de correspondência de regras

O bloco match de uma regra de federação determina se um JWT recebido é aceito. Todos os campos preenchidos são avaliados com semântica AND: o JWT deve satisfazer todos os matchers preenchidos. Pelo menos um entre subject_prefix, claims ou condition deve estar definido; um bloco match que contém apenas audience (ou nenhum matcher) é rejeitado. Isso protege contra regras que aceitariam todos os tokens de um emissor.

Ambiente de avaliação CEL

A expressão condition tem acesso a uma única variável:

Exemplo:

claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]

Erros

Erros de troca de token

POST /v1/oauth/token retorna erros no formato de erro padrão da API. O SDK encapsula falhas de troca em um FederationExchangeError tipado (ou equivalente na linguagem) que expõe o status HTTP, o corpo da resposta e o request_id.

Toda negação de assertion retorna o mesmo 401 authentication_error opaco com a mensagem fixa Authentication failed, independentemente de qual verificação falhou; um erro distinguível permitiria que um chamador sondasse a configuração da regra. O motivo da negação é registrado na entrada da tentativa no histórico de autenticação, por exemplo match_subject_prefix quando a claim sub falha no subject_prefix da regra, ou workspace_id_required quando a regra abrange vários workspaces e a requisição não nomeia nenhum. Requisições rejeitadas antes que a organização da regra seja corroborada (a família 400 invalid_request_error acima) não deixam entrada no histórico; suas mensagens de resposta indicam o problema diretamente. Um 401 sem entrada correspondente no histórico geralmente significa que o próprio federation_rule_id não foi reconhecido.

Falhas comuns do lado do SDK

Solucionar uma troca com falha

Uma resposta 401 authentication_error é intencionalmente opaca e sua mensagem é sempre Authentication failed; o motivo da negação é registrado no histórico de autenticação, não na resposta.

Uma falha opaca comum é uma assertion reutilizada: uma assertion que contém uma claim jti pode ser trocada apenas uma vez, portanto uma carga de trabalho que reenvia o mesmo JWT (um loop de retry, ou uma renovação que relê um token não rotacionado) é rejeitada na segunda troca. A página de histórico de autenticação mostra essas tentativas com o motivo jti_reused; a correção é emitir uma assertion nova para cada troca.

Se você ainda precisar depurar a partir do próprio JWT, siga estas verificações em ordem:

1. 1

   Decodifique o JWT

   Decodifique a assertion que você enviou para poder comparar cada claim com a configuração do seu emissor e da sua regra:

   cURL

   

   jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"

2. 2

   Verifique se iss corresponde ao emissor

   A claim iss decodificada deve ser igual ao issuer_url registrado byte a byte, incluindo esquema, porta e qualquer barra final. Uma divergência em um único caractere faz a verificação falhar.

3. 3

   Verifique se aud corresponde à regra

   A claim aud decodificada deve conter o valor audience da regra como correspondência exata. Quando aud é um array, um elemento deve corresponder exatamente.

4. 4

   Verifique sub e cada entrada de claims

   Compare sub com o subject_prefix da regra (sensível a maiúsculas e minúsculas; um * no final é correspondência de prefixo, qualquer outra coisa é exata). Compare cada chave no mapa claims da regra com a claim de nível superior de mesmo nome.

5. 5

   Verifique exp, nbf e iat

   exp deve estar no futuro e nbf/iat devem estar no passado, dentro da janela de desvio de 30 segundos. Se o relógio do host da carga de trabalho tiver se desviado, um token de outra forma válido é rejeitado.

6. 6

   Verifique a acessibilidade do JWKS

   Para o modo discovery, busque <jwks.discovery_base or issuer_url>/.well-known/openid-configuration via HTTPS público na porta 443 e confirme que jwks_uri resolve. Para explicit_url, busque a URL do JWKS diretamente. Para inline, confirme que a chave de assinatura do emissor não foi rotacionada desde que você registrou as chaves.

   Se o emissor rotacionou sua chave de assinatura e começou imediatamente a assinar com ela, as trocas podem falhar por até um minuto enquanto o cache de JWKS da Anthropic é atualizado. Consulte Rotação de chaves e cache.

Modos de origem do JWKS

Quando você registra um emissor de federação, o campo jwks controla como a Anthropic obtém as chaves públicas usadas para verificar assinaturas de JWT desse emissor. É uma união discriminada com chave em type:

A união discriminada torna os campos complementares mutuamente exclusivos por construção. Tanto discovery quanto explicit_url também aceitam uma string opcional ca_cert_pem para emissores que servem TLS a partir de uma CA privada.

Rotação de chaves e cache

Nos modos discovery e explicit_url, a Anthropic armazena em cache o JWKS buscado. Se seu provedor de identidade publicar uma nova chave de assinatura e começar imediatamente a assinar tokens com ela, as trocas que apresentarem esses tokens podem falhar com um erro de assinatura por até 1 minuto enquanto o cache é atualizado.

Para evitar essa janela, publique uma nova chave de assinatura no JWKS pelo menos 15 minutos antes de seu provedor de identidade começar a assinar tokens com ela, e mantenha a chave substituída no JWKS até que os tokens assinados por ela tenham expirado. Provedores de identidade gerenciados normalmente seguem essa disciplina por conta própria. Se você opera seu próprio emissor (um cluster Kubernetes autogerenciado, um provedor de discovery OIDC SPIRE ou um servidor de autorização personalizado do Okta com uma cadência de rotação configurada), confirme que sua política de rotação publica novas chaves antes do primeiro uso.