Usar WIF com Okta

O Okta pode atuar como um provedor de identidade de workload emitindo tokens de acesso OIDC para um service application (aplicativo 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. Certifique-se de 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.

Configurar o Okta

Em linhas gerais, você precisa:

1. Criar um aplicativo 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. As etapas numeradas a seguir percorrem um caminho comum:

1. Crie uma integração de aplicativo de serviço. No Okta Admin Console, crie uma nova integração de aplicativo 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. Como alternativa, use um segredo de cliente se seu ambiente puder armazená-lo com segurança. Para o exemplo a seguir, talvez você precise desabilitar o requisito de DPoP no aplicativo; certifique-se de que sua configuração de produção esteja em conformidade com 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 em relação a esse valor fixo.
4. Conceda um escopo. No seu servidor de autorização personalizado, garanta que exista pelo menos um escopo que o aplicativo 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 aplicativo de serviço solicite o escopo concedido na etapa 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 aplicativo de serviço usando client_credentials, o Okta define a claim sub do token de acesso emitido como o Client ID do aplicativo, e iss como a URL do emissor do servidor de autorização.

Configurar 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 aplicativo 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
}

Obter um token e chamar 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 ao SDK da Anthropic como o token de identidade.

import os
import httpx2
import anthropic
from anthropic import WorkloadIdentityCredentials


def fetch_okta_token() -> str:
    response = httpx2.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",
            # Crie o JWT client_assertion 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 função chamável: o SDK da Anthropic chama novamente seu provedor de token de identidade sempre que o token de acesso da Anthropic se aproxima da expiração, portanto 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 periodicamente com um temporizador para shells de longa duração.

Verificar a configuração

Uma troca bem-sucedida retorna um access_token começando com sk-ant-oat01- e um valor expires_in em segundos. Se a troca falhar com a resposta opaca 401 authentication_error (mensagem Authentication failed), verifique a página de histórico de autenticação para ver o motivo da negação e 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 pode ser usado).

Delimitar o escopo da sua regra

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

• Fixe o Client ID exato: Defina subject_prefix como o Client ID completo do aplicativo de serviço, sem * no final.
• Fixe a audiência: Faça correspondência com o 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 aplicativo de serviço: Crie uma regra de federação separada para cada aplicativo de serviço em vez de compartilhar uma regra entre aplicativos.

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.