Usar 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 do grant client_credentials do OAuth 2.0. Seu workload se autentica no Okta (normalmente com private_key_jwt, para que nenhum segredo compartilhado seja 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 sua configuração e mecanismos de 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 acessar api.anthropic.com.

Configurar o Okta

Em linhas gerais, você precisa:

1. Criar uma aplicação de serviço no 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 que você queira usar para 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 abaixo percorrem um caminho comum:

1. Crie uma integração de aplicação de serviço. No Okta Admin Console, crie uma nova integração de aplicação do tipo API Services (OIDC, machine-to-machine). 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 client secret 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; 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, certifique-se de que exista pelo menos um escopo que a aplicação 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 sua aplicação de serviço solicite o escopo que você concedeu na etapa 4.
6. (Opcional) Adicione claims personalizadas. Se você quiser fazer correspondência com algo diferente do client ID, adicione uma claim ao token de acesso na aba Claims do seu servidor de autorização.

Para uma aplicação 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.

Configurar a Anthropic

Siga o passo a passo de configuração para registrar um emissor de federação, criar uma conta de serviço da Anthropic e criar uma regra de federação no Claude Console. Use estes valores específicos do Okta.

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_source": "discovery"
}

Regra de federação: Faça a correspondência com a claim sub do Okta, que é o Client ID da aplicação de serviço. Se você definiu claims personalizadas no Okta, pode fazer a correspondência com elas usando 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 API do Claude

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-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message.content[0].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 fetcher 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 em um timer 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. 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).

Delimitar 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 da aplicação de serviço, sem * no final.
• Fixe a audiência: Faça 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 com claims personalizadas: Para um escopo mais granular, adicione claims na aba Claims do servidor de autorização e faça a correspondência com elas usando o mapa claims da regra ou uma condition CEL.
• Use uma regra por aplicação de serviço: Crie uma regra de federação separada para cada aplicação de serviço em vez de compartilhar uma regra entre aplicações.

Próximos passos

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