Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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 tutoriais de configuração, consulte os guias de provedores.
POST /v1/oauth/token aceita um corpo JSON usando o grant jwt-bearer do 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.
| Campo | Obrigatório | Descrição |
|---|---|---|
grant_type | Sim | Sempre urn:ietf:params:oauth:grant-type:jwt-bearer. |
assertion | Sim | O JWT OIDC emitido pelo seu provedor de identidade. |
federation_rule_id | Sim | ID com tag (fdrl_...) da regra de federação a ser avaliada. |
organization_id | Sim | UUID da sua organização Anthropic. |
service_account_id | Sim | ID com tag (svac_...) da conta de serviço de destino. |
workspace_id | Condicional | ID com tag (wrkspc_...) do workspace ao qual o token emitido será limitado, ou o literal default para o workspace padrão da organização. Obrigatório quando a regra está habilitada para mais de um workspace. Quando omitido, o servidor seleciona o único workspace habilitado da regra. |
POST /v1/oauth/token retorna uma resposta de token OAuth 2.0 padrão (RFC 6749 §5.1):
| Campo | Tipo | Descrição |
|---|---|---|
access_token | string | O token Anthropic de curta duração, com prefixo sk-ant-oat01-.... Passe-o como Authorization: Bearer <token>. |
token_type | string | Sempre Bearer. |
expires_in | integer | Segundos até o token expirar. |
scope | string | O escopo OAuth concedido pela regra correspondente. |
O SDK lê estas variáveis para realizar uma troca de token federada sem argumentos de construtor.
| Variável | Obrigatória | Descrição | Exemplo |
|---|---|---|---|
ANTHROPIC_FEDERATION_RULE_ID | Sim | ID com tag da regra de federação a ser avaliada. | fdrl_... |
ANTHROPIC_ORGANIZATION_ID | Sim | UUID da sua organização Anthropic. Encontre-o no Claude Console em Settings > Organization. | 00000000-0000-0000-0000-000000000000 |
ANTHROPIC_IDENTITY_TOKEN_FILE | Uma entre _TOKEN_FILE ou _TOKEN | Caminho no sistema de arquivos para o JWT emitido pelo seu "identity provider" (provedor de identidade), ou IdP. O SDK relê este arquivo a cada troca para que tokens projetados que rotacionam em disco estejam sempre atualizados. | /var/run/secrets/anthropic.com/token |
ANTHROPIC_IDENTITY_TOKEN | Uma entre _TOKEN_FILE ou _TOKEN | O JWT literal como uma string. Use quando sua plataforma injeta o token como uma variável de ambiente em vez de um arquivo. | eyJhbGciOiJSUzI1NiIs... |
ANTHROPIC_SERVICE_ACCOUNT_ID | Sim | ID com tag da conta de serviço Anthropic de destino como a qual o token de acesso emitido atua. | svac_... |
ANTHROPIC_WORKSPACE_ID | Condicional | ID com tag do workspace ao qual o token emitido será limitado, ou o literal default. Obrigatório quando a regra de federação está habilitada para mais de um workspace; opcional quando a regra está vinculada a um único workspace. O token emitido é limitado a este workspace no momento da troca, portanto trocar de workspace requer uma nova troca. | wrkspc_... |
ANTHROPIC_PROFILE | Não | Nome de um perfil de configuração a ser carregado. Tem precedência sobre as variáveis de ambiente de federação nesta tabela. | staging-profile |
O caminho de federação direto por variáveis de ambiente é ativado apenas 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.
Uma variável definida como uma string vazia ainda ocupa seu lugar na cadeia de precedência de credenciais. Se ANTHROPIC_API_KEY="" for exportada, o SDK seleciona o caminho de API key com uma chave vazia em vez de passar para a federação. Remova a definição das variáveis de credenciais não utilizadas em vez de deixá-las em branco.
O SDK resolve credenciais nesta ordem. A primeira fonte que produz uma credencial vence.
| Ordem | Fonte | Observações |
|---|---|---|
| 1 | Argumento de construtor (api_key=, auth_token=, credentials=) | Sempre sobrepõe todo o resto. |
| 2 | ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN | Oculta a federação completamente. Remova a definição destas ao migrar de chaves de API. |
| 3 | ANTHROPIC_PROFILE | Carrega <config_dir>/configs/<name>.json. Um perfil nomeado ausente é um erro, não um fallback. |
| 4 | Variáveis de ambiente de federação | ANTHROPIC_FEDERATION_RULE_ID + ANTHROPIC_ORGANIZATION_ID + ANTHROPIC_SERVICE_ACCOUNT_ID + ANTHROPIC_IDENTITY_TOKEN[_FILE]. |
| 5 | Perfil ativo | Resolvido a partir de <config_dir>/active_config, com fallback para um perfil chamado default. |
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 apenas quando o perfil ativo não o define.
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.
O SDK localiza o diretório de configuração nesta ordem:
$ANTHROPIC_CONFIG_DIR~/.config/anthropic no Linux e macOS%APPDATA%\Anthropic no WindowsO nome do perfil ativo é resolvido nesta ordem:
$ANTHROPIC_PROFILE<config_dir>/active_config (um arquivo de uma linha escrito por ant profile activate <name>)defaultO Claude Code e o Claude Agent SDK respeitam esta mesma ordem de resolução, portanto um perfil de federação configurado aqui também autentica essas ferramentas sem configuração adicional.
| Caminho | Conteúdo | Sensibilidade |
|---|---|---|
<config_dir>/configs/<profile>.json | version, o bloco authentication, organization_id, workspace_id e base_url. | Não secreto. Seguro para fazer commit ou incorporar em uma imagem. |
<config_dir>/credentials/<profile>.json | version, o access_token em cache, expires_at e (para login interativo) refresh_token. | Secreto. Escrito pelo SDK com modo 0600. |
Tanto o arquivo de configuração quanto o arquivo de credenciais carregam um campo string de nível superior version no formato major.minor (atualmente "1.0"). O SDK escreve este 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.
{
"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.
O oauth_scope que você define em uma regra de federação determina quais endpoints da API do Claude o token de acesso emitido pode chamar.
| Escopo | Concede acesso a |
|---|---|
workspace:developer | Todos os endpoints não administrativos da API do Claude no workspace da regra: Messages (incluindo streaming e contagem de tokens), Models, Managed Agents e suas sessões, Files e Skills. Isso corresponde ao acesso que uma chave de API emitida para o mesmo workspace possui. |
workspace:inference | Os endpoints de inferência no workspace da regra: Messages (incluindo streaming e contagem de tokens), Models e o endpoint de chat compatível com OpenAI. Use isto para cargas de trabalho que só precisam chamar o Claude e nunca precisam gerenciar Files, Skills ou outros recursos. |
workspace:manage_tunnels | A API de túneis MCP: criar, listar e obter túneis, registrar e arquivar certificados de CA, revelar e rotacionar o token do túnel e arquivar túneis. A janela modal de criação de túnel do Console trava este escopo quando você cria uma regra a partir dela. |
org:admin | Acesso completo à Admin API (membros da organização, convites, workspaces, chaves de API e o restante). Um token OAuth org:admin só pode criar ou modificar regras com escopo workspace:developer ou workspace:inference, e não pode atualizar um emissor que sustenta uma regra com qualquer outro escopo; consulte as restrições. |
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.
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 do papel da conta de serviço.
oauth_scope da regra | organization_role da conta de serviço | Permissões efetivas |
|---|---|---|
workspace:developer | admin | Acesso à API do Claude apenas no workspace da regra. O escopo limita o token abaixo do papel. |
org:admin | admin | Acesso completo à Admin API (membros da organização, convites, workspaces, chaves de API e o restante), menos as exceções para chamadores OAuth; consulte as restrições. |
A Anthropic impõe estas 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.
| Campo | Restrição |
|---|---|
name de emissor, regra e conta de serviço | Deve corresponder a ^[a-z0-9-]+$, comprimento de 1 a 255 caracteres. |
workspace_id | Obrigatório na criação, a menos que applies_to_all_workspaces seja true. O workspace (wrkspc_...) cuja cota, faturamento e limites de taxa se aplicam aos tokens emitidos sob esta regra. Deve ser um workspace na mesma organização, e a conta de serviço de destino deve ser membro desse workspace. |
applies_to_all_workspaces | Booleano. Defina como true para habilitar a regra em todos os workspaces da organização em vez de nomear um; este ou workspace_id é obrigatório na criação. |
token_lifetime_seconds | Inteiro entre 60 e 86400 (1 minuto a 24 horas). Padrão 3600. Valores fora deste intervalo são rejeitados no momento da requisição. Consulte Tempo de vida e renovação do token. |
Os campos issuer_url, jwks.discovery_base e jwks.url são validados:
| Restrição | Detalhe |
|---|---|
| Esquema | Deve ser https. |
| Porta | Deve ser 443 (explícita ou padrão). |
| Host | Deve ser um nome de host DNS público para seu provedor OIDC. Deve resolver para endereços IP públicos; literais de IP não são aceitos. |
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).
As restrições de URL se aplicam apenas a URLs que a Anthropic acessa. Nos modos JWKS explicit_url e inline, e no modo discovery quando jwks.discovery_base está definido, o issuer_url é comparado com a claim iss do JWT como uma string e nunca é buscado, portanto pode referenciar um nome de host interno ou uma porta não padrão.
| Restrição | Detalhe |
|---|---|
| Tamanho máximo | O JWT assertion deve ter no máximo 16 KiB. |
| Algoritmo de assinatura | Apenas algoritmos assimétricos (famílias RSA e ECDSA: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512) são aceitos. HMAC (HS256, HS384, HS512) e none são rejeitados. |
| ID da chave | O cabeçalho do JWT deve conter um kid que corresponda a uma chave no JWKS do emissor. Tokens sem kid são rejeitados. |
| Claims obrigatórias | sub deve estar presente. iat deve estar presente e não estar no futuro. exp deve estar presente e estar no futuro. |
| Tempo de vida máximo | O tempo de vida do token (exp menos iat) não deve exceder o máximo configurado do emissor (1 hora por padrão, configurável para cada emissor no Claude Console). |
| Desvio de relógio | Uma tolerância de 30 segundos é aplicada a exp, nbf e iat. |
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.
| Matcher | Tipo | Semântica |
|---|---|---|
subject_prefix | string | Correspondência exata com a claim sub do JWT. Um * no final o torna uma correspondência de prefixo (o valor de sub deve começar com os caracteres antes do *). Diferencia maiúsculas de minúsculas. |
audience | string | A claim aud do JWT deve conter esta string exata. Quando aud é um array, qualquer elemento que corresponda exatamente satisfaz a verificação. |
claims | map<string, string> | Cada chave é um nome de claim de nível superior e cada valor é o valor de string exato exigido. Para claims aninhadas, numéricas, booleanas ou complexas como listas e mapas, use condition com uma expressão CEL em vez disso. |
condition | string (CEL) | Uma expressão CEL que deve ser avaliada como true. |
A expressão condition tem acesso a uma única variável:
| Variável | Tipo | Conteúdo |
|---|---|---|
claims | map | O conjunto completo de claims do JWT decodificado. Objetos aninhados são acessíveis como mapas aninhados. |
Exemplo:
claims.sub.startsWith("repo:acme-corp/") && claims.ref in ["refs/heads/main", "refs/heads/release"]Condições CEL são limites de segurança. Uma expressão que é avaliada como true para mais entradas do que o pretendido concede acesso mais amplo do que o pretendido. Prefira os matchers estáticos quando eles expressarem sua restrição.
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.
| Status | Erro | Causa | Resolução |
|---|---|---|---|
| 400 | invalid_request | federation_rule_id está malformado ou um campo obrigatório da requisição está ausente. | Verifique o ID fdrl_ e se o corpo da requisição inclui todos os campos obrigatórios. |
| 400 | invalid_request | workspace_id_required: a regra de federação está habilitada para mais de um workspace e a requisição omite workspace_id. | Defina ANTHROPIC_WORKSPACE_ID (ou o campo workspace_id do corpo em uma requisição bruta) para o ID wrkspc_... ao qual você quer que o token seja limitado. Consulte Requisição de troca de token. |
| 400 | invalid_grant | A claim iss do JWT não é exatamente igual ao issuer_url registrado. | Compare byte a byte, incluindo barras finais e esquema: jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson | .iss' <<< "$JWT". |
| 400 | invalid_grant | A busca do JWKS falhou, o JWKS está desatualizado ou o JWT foi assinado com uma chave que não está no JWKS. | Para o modo inline, atualize o emissor com as chaves rotacionadas. Para discovery e explicit_url, confirme que o endpoint JWKS está acessível na porta 443; se o emissor rotacionou recentemente sua chave de assinatura, consulte Rotação de chaves e cache. |
| 400 | invalid_grant | A claim exp do JWT está no passado (além da janela de desvio de 30 segundos). | Confirme que seu provedor de identidade está projetando um token atualizado e que o SDK está relendo o arquivo do token. |
| 400 | invalid_grant | O JWT foi verificado, mas suas claims não satisfazem o bloco match da regra. | Decodifique o JWT e compare cada claim com a regra. subject_prefix diferencia maiúsculas de minúsculas. audience requer uma correspondência exata de elemento. |
| 400 | invalid_grant | O federation_rule_id não existe, está arquivado ou o JWT não está autorizado para ele (consolidado para evitar enumeração). | Confirme o ID da regra no Claude Console e que a regra não foi arquivada. |
Todas as falhas invalid_grant retornam HTTP 400; a causa específica é registrada apenas no lado do servidor e não é exposta na resposta.
| Sintoma | Causa | Resolução |
|---|---|---|
| O SDK reporta "no credentials" em vez de fazer a troca | Uma entre ANTHROPIC_FEDERATION_RULE_ID, ANTHROPIC_ORGANIZATION_ID, ANTHROPIC_SERVICE_ACCOUNT_ID ou ANTHROPIC_IDENTITY_TOKEN[_FILE] não está definida e nenhum perfil está ativo. | Defina as quatro variáveis ou configure um perfil. |
| O SDK autentica com uma chave de API em vez de federar | ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN está definida e vence na precedência. | Remova a definição da variável de chave ou token. |
FileNotFoundError na primeira requisição | O caminho em ANTHROPIC_IDENTITY_TOKEN_FILE não existe. O SDK abre o arquivo de forma preguiçosa no momento da troca. | Confirme que o volume do token projetado está montado e que o caminho corresponde. |
| A troca de token é bem-sucedida, mas uma requisição à API do Claude retorna 403 | O escopo do token emitido não concede acesso a esse endpoint. | Verifique o oauth_scope da regra em relação aos escopos OAuth. |
| A autenticação falha com credencial vazia | Uma variável de ambiente de credencial está exportada, mas definida como uma string vazia. Valores vazios ainda vencem em seu lugar na precedência. | Remova a definição da variável com unset VAR em vez de VAR="". |
Uma resposta 400 invalid_grant é intencionalmente opaca; a causa específica é registrada apenas no lado do servidor.
Comece pela página de histórico de autenticação no Claude Console. Tentativas de troca recentes mostram o emissor e a regra que foram avaliados, as claims do JWT que foram inspecionadas e qual etapa de validação falhou, o que geralmente torna desnecessárias as verificações a seguir.
Se você ainda precisar depurar a partir do próprio JWT, siga estas verificações em ordem:
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:
jq -rR 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson' <<< "$JWT"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.
Verifique se aud corresponde à regra
A claim aud decodificada deve conter o valor audience da regra como uma correspondência exata. Quando aud é um array, um elemento deve corresponder exatamente.
Verifique sub e cada entrada de claims
Compare sub com o subject_prefix da regra (diferencia maiúsculas de minúsculas; um * no final é uma 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.
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 desviado, um token que seria válido é rejeitado.
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 rotacionou desde que você registrou as chaves.
Se o emissor rotacionou sua chave de assinatura e imediatamente começou 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.
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:
jwks.type | Formato de jwks | Comportamento | Use quando |
|---|---|---|---|
discovery (padrão) | { "type": "discovery", "discovery_base": "https://..." } (discovery_base é opcional; defina-o quando a URL de descoberta difere de issuer_url) | A Anthropic busca <discovery_base or issuer_url>/.well-known/openid-configuration, lê jwks_uri do documento de descoberta e busca o JWKS a partir dele. | Seu IdP serve um documento de descoberta OIDC padrão na internet pública. A maioria dos provedores gerenciados (EKS, GKE, Cloud Run, GitHub Actions, Entra ID) oferece suporte a isso. |
explicit_url | { "type": "explicit_url", "url": "https://..." } | A Anthropic busca o JWKS diretamente de url. O issuer_url é usado apenas para comparação de string com a claim iss do JWT e nunca é acessado. | Seu IdP não serve um documento de descoberta, ou a descoberta é apenas interna, mas o JWKS é publicamente acessível. |
inline | { "type": "inline", "keys": [...] } | Você fornece o array de objetos JWK inline (o array keys do documento JWKS, não o objeto envoltório). A Anthropic não faz nenhuma requisição de saída. O issuer_url é usado apenas para comparação de iss. | Ambientes isolados (air-gapped), clusters Kubernetes autogerenciados com URLs de emissor internas ao cluster, ou quando você quer controle explícito sobre a rotação de chaves. |
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.
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 imediatamente começar a assinar tokens com ela, as trocas que apresentam 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 que ela assinou 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 descoberta 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.
No modo inline não há atualização automática de chaves. Quando seu provedor de identidade rotaciona suas chaves de assinatura, você deve atualizar a configuração do emissor com o novo JWKS ou todas as trocas de token falharão na verificação de assinatura.
Was this page helpful?