Use WIF com Okta

O Okta pode atuar como um provedor de identidade de workload emitindo tokens de acesso OIDC para uma aplicação de serviço por meio da concessão client_credentials do OAuth 2.0. Seu workload se autentica no Okta (normalmente com private_key_jwt, de modo que nenhum segredo compartilhado é armazenado), recebe um "JSON Web Token" (token web JSON), ou JWT, assinado e troca esse JWT com a Anthropic por um token de acesso de curta duração.

A URL do emissor do servidor de autorização do Okta tem o formato https://<your-domain>.okta.com/oauth2/<auth-server-id>. Se você usar o servidor padrão integrado, o caminho é /oauth2/default.

Existem muitas maneiras de configurar e autenticar no Okta que estão fora do escopo desta documentação. Garanta que seus mecanismos de configuração e autenticação sigam as orientações e práticas de segurança da sua empresa.



Pré-requisitos

• Familiaridade com os conceitos de WIF: contas de serviço, emissores de federação e regras de federação.
• Uma organização Okta com API Access Management habilitado (necessário para servidores de autorização personalizados).
• Permissão para criar contas de serviço, emissores de federação e regras de federação no Claude Console para sua organização Anthropic.
• Um workload que possa solicitar um token do endpoint /v1/token do Okta e alcançar api.anthropic.com.



Configure o Okta

Em alto nível, você precisa:

1. Criar uma aplicação de serviço do Okta.
2. Configurar seu servidor de autorização padrão (ou criar um novo servidor de autorização personalizado) com uma audiência, um escopo, uma política de acesso e quaisquer claims personalizadas nas quais você queira fazer correspondência.

A navegação exata depende da configuração da sua organização Okta e da versão do console de administração. Os passos numerados a seguir percorrem um caminho comum:

1. Crie uma integração de app de serviço. No Okta Admin Console, crie uma nova integração de app do tipo API Services (OIDC, máquina a máquina). Anote o Client ID gerado.
2. Configure a autenticação do cliente. Para uma configuração sem chaves, escolha Public key / Private key (private_key_jwt) e registre a JWK pública do seu workload. Alternativamente, use um segredo de cliente se seu ambiente puder armazená-lo com segurança. Para o exemplo a seguir, pode ser necessário desabilitar o requisito de DPoP na aplicação; garanta que sua configuração de produção siga os requisitos de segurança da sua organização.
3. Defina a audiência. No seu servidor de autorização personalizado, defina a audiência como https://api.anthropic.com para que os tokens de acesso emitidos carreguem essa claim aud. A Anthropic valida aud contra esse valor fixo.
4. Conceda um escopo. No seu servidor de autorização personalizado, garanta que exista pelo menos um escopo que o app de serviço tenha permissão para solicitar (por exemplo, anthropic.access). O Okta rejeita solicitações client_credentials que não incluam um escopo concedido.
5. Crie uma política de acesso. No seu servidor de autorização personalizado, crie uma política de acesso com pelo menos uma regra que permita que seu app de serviço solicite o escopo concedido no passo 4.
6. (Opcional) Adicione claims personalizadas. Se você quiser fazer correspondência em algo diferente do client ID, adicione uma claim ao token de acesso na aba Claims do seu servidor de autorização.

Para um app de serviço usando client_credentials, o Okta define a claim sub do token de acesso emitido como o Client ID da aplicação, e iss como a URL do emissor do servidor de autorização.



Configure a Anthropic

No Claude Console, abra Settings → Workload identity, clique em Connect workload e selecione Custom OIDC. O assistente orienta você no registro do emissor, na criação de uma conta de serviço e na criação de uma regra de federação.

O assistente cria esses recursos para você. Use os seguintes valores, seja inserindo-os no assistente ou enviando-os para a Admin API:

Emissor de federação: Use a URL do seu servidor de autorização personalizado do Okta e o modo de descoberta. A Anthropic lê o documento de descoberta .well-known/openid-configuration do Okta e busca o JWKS a partir do jwks_uri que ele anuncia.

{
  "name": "okta-prod",
  "issuer_url": "https://acme.okta.com/oauth2/aus1a2b3c4d5e6f7g8h9",
  "jwks": { "type": "discovery" }
}

Regra de federação: Faça correspondência na claim sub do Okta, que é o Client ID do app de serviço. Se você definiu claims personalizadas no Okta, pode fazer correspondência nelas em vez disso com o mapa claims ou uma condition CEL.

{
  "name": "okta-pipeline",
  "issuer_id": "fdis_...",
  "match": {
    "subject_prefix": "0oa1b2c3d4e5f6g7h8i9",
    "audience": "https://api.anthropic.com"
  },
  "target": { "type": "service_account", "service_account_id": "svac_..." },
  "workspace_id": "wrkspc_...",
  "oauth_scope": "workspace:developer",
  "token_lifetime_seconds": 600
}



Adquira um token e chame a Claude API

Diferentemente dos provedores nativos de plataforma (AWS, Google Cloud, Kubernetes), que disponibilizam um token dentro do runtime do workload (por meio de um arquivo projetado ou endpoint de metadados local), o Okta não faz isso. Seu workload deve chamar o endpoint de token do Okta para obter um JWT e, em seguida, passar esse JWT para o SDK da Anthropic como o token de identidade.

import os
import httpx
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx.post(
        f"{os.environ['OKTA_ISSUER']}/v1/token",
        data={
            "grant_type": "client_credentials",
            "scope": "anthropic.access",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            # Construa o JWT client_assertion do RFC 7523 assinado com a chave privada do seu app Okta
            "client_assertion": build_signed_client_assertion(),
        },
    )
    response.raise_for_status()
    return response.json()["access_token"]


client = anthropic.Anthropic(
    credentials=WorkloadIdentityCredentials(
        identity_token_provider=fetch_okta_token,
        federation_rule_id=os.environ["ANTHROPIC_FEDERATION_RULE_ID"],
        organization_id=os.environ["ANTHROPIC_ORGANIZATION_ID"],
        service_account_id=os.environ["ANTHROPIC_SERVICE_ACCOUNT_ID"],
        workspace_id=os.environ.get("ANTHROPIC_WORKSPACE_ID"),
    ),
)

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"))

Cada aba de SDK mostra o padrão de callable: o SDK da Anthropic chama seu provedor de token de identidade novamente sempre que o token de acesso da Anthropic se aproxima da expiração, então seu buscador do Okta deve retornar um token novo a cada chamada em vez de armazenar um em cache indefinidamente. A CLI ant relê ANTHROPIC_IDENTITY_TOKEN_FILE a cada troca, então atualize esse arquivo com um temporizador para shells de longa duração.



Verifique a configuração

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Em caso de 400 invalid_grant, consulte Solucionar problemas de uma troca com falha; a causa mais comum do lado do Okta é uma incompatibilidade de issuer_url (ela deve incluir o caminho /oauth2/<auth-server-id>; o servidor de autorização da organização Okta não é utilizável).



Delimite o escopo da sua regra

Restrinja o bloco match da regra ao escopo mais estreito que se adeque ao seu caso de uso:

• Fixe o Client ID exato: Defina subject_prefix como o Client ID completo do app de serviço sem * no final.
• Fixe a audiência: Faça correspondência no valor de audience que você configurou no servidor de autorização para que tokens emitidos para uma audiência diferente sejam rejeitados.
• Faça correspondência em claims personalizadas: Para um escopo mais granular, adicione claims na aba Claims do servidor de autorização e faça correspondência nelas com o mapa claims da regra ou uma condition CEL.
• Use uma regra por app de serviço: Crie uma regra de federação separada para cada app de serviço em vez de compartilhar uma regra entre apps.



Próximos passos

• Revise a referência de WIF para a ordem completa de resolução de credenciais e a configuração de perfis.
• Consulte a referência de WIF para fazer correspondência em claims personalizadas do Okta com expressões CEL.