Usar WIF con Okta

Okta puede actuar como proveedor de identidad de cargas de trabajo emitiendo tokens de acceso OIDC a una aplicación de servicio mediante la concesión client_credentials de OAuth 2.0. Tu carga de trabajo se autentica en Okta (normalmente con private_key_jwt, de modo que no se almacena ningún secreto compartido), recibe un JSON Web Token (JWT) firmado e intercambia ese JWT con Anthropic por un token de acceso de corta duración.

La URL del emisor del servidor de autorización de Okta tiene la forma https://<your-domain>.okta.com/oauth2/<auth-server-id>. Si usas el servidor predeterminado integrado, la ruta es /oauth2/default.

Existen muchas formas de configurar Okta y autenticarse en él que están fuera del alcance de esta documentación. Asegúrate de que tus mecanismos de configuración y autenticación sigan las directrices y prácticas de seguridad de tu empresa.

Requisitos previos

• Familiaridad con los conceptos de WIF: cuentas de servicio, emisores de federación y reglas de federación.
• Una organización de Okta con API Access Management habilitado (necesario para los servidores de autorización personalizados).
• Permiso para crear cuentas de servicio, emisores de federación y reglas de federación en la Claude Console para tu organización de Anthropic.
• Una carga de trabajo que pueda solicitar un token al endpoint /v1/token de Okta y alcanzar api.anthropic.com.

Configurar Okta

A grandes rasgos, necesitas:

1. Crear una aplicación de servicio de Okta.
2. Configurar tu servidor de autorización predeterminado (o crear un nuevo servidor de autorización personalizado) con una audiencia, un scope, una política de acceso y cualquier claim personalizado con el que quieras hacer coincidencias.

La navegación exacta depende de la configuración de tu organización de Okta y de la versión de la consola de administración. Los siguientes pasos numerados recorren una ruta común:

1. Crea una integración de aplicación de servicio. En la Okta Admin Console, crea una nueva integración de aplicación de tipo API Services (OIDC, máquina a máquina). Anota el Client ID generado.
2. Configura la autenticación del cliente. Para una configuración sin claves almacenadas, elige Public key / Private key (private_key_jwt) y registra la JWK pública de tu carga de trabajo. Como alternativa, usa un secreto de cliente si tu entorno puede almacenarlo de forma segura. Para el siguiente ejemplo, es posible que debas deshabilitar el requisito de DPoP en la aplicación; asegúrate de que tu configuración de producción cumpla con los requisitos de seguridad de tu organización.
3. Establece la audiencia. En tu servidor de autorización personalizado, establece la audiencia en https://api.anthropic.com para que los tokens de acceso emitidos lleven ese claim aud. Anthropic valida aud contra este valor fijo.
4. Concede un scope. En tu servidor de autorización personalizado, asegúrate de que exista al menos un scope que la aplicación de servicio tenga permitido solicitar (por ejemplo, anthropic.access). Okta rechaza las solicitudes client_credentials que no incluyan un scope concedido.
5. Crea una política de acceso. En tu servidor de autorización personalizado, crea una política de acceso con al menos una regla que permita a tu aplicación de servicio solicitar el scope que concediste en el paso 4.
6. (Opcional) Agrega claims personalizados. Si quieres hacer coincidencias con algo distinto del Client ID, agrega un claim al token de acceso en la pestaña Claims de tu servidor de autorización.

Para una aplicación de servicio que usa client_credentials, Okta establece el claim sub del token de acceso emitido en el Client ID de la aplicación, y iss en la URL del emisor del servidor de autorización.

Configurar Anthropic

En la Claude Console, abre Settings → Workload identity, haz clic en Connect workload y selecciona Custom OIDC. El asistente te guía para registrar el emisor, crear una cuenta de servicio y crear una regla de federación.

El asistente crea estos recursos por ti. Usa los siguientes valores, ya sea que los ingreses en el asistente o los envíes a la Admin API:

Emisor de federación: Usa la URL de tu servidor de autorización personalizado de Okta y el modo de descubrimiento. Anthropic lee el documento de descubrimiento .well-known/openid-configuration de Okta y obtiene el JWKS desde el jwks_uri que este anuncia.

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

Regla de federación: Haz la coincidencia con el claim sub de Okta, que es el Client ID de la aplicación de servicio. Si definiste claims personalizados en Okta, puedes hacer la coincidencia con ellos en su lugar mediante el mapa claims o una 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
}

Obtener un token y llamar a la Claude API

A diferencia de los proveedores nativos de plataforma (AWS, Google Cloud, Kubernetes), que ponen un token a disposición dentro del entorno de ejecución de la carga de trabajo (mediante un archivo proyectado o un endpoint de metadatos local), Okta no lo hace. Tu carga de trabajo debe llamar al endpoint de tokens de Okta para obtener un JWT y luego pasar ese JWT al SDK de Anthropic como token de identidad.

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",
            # Construye el JWT client_assertion de RFC 7523 firmado con la clave privada de tu app de 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 pestaña de SDK muestra el patrón de función invocable: el SDK de Anthropic vuelve a llamar a tu proveedor de token de identidad cada vez que el token de acceso de Anthropic se acerca a su vencimiento, por lo que tu función de obtención de Okta debe devolver un token nuevo en cada llamada en lugar de almacenar uno en caché indefinidamente. La CLI ant vuelve a leer ANTHROPIC_IDENTITY_TOKEN_FILE en cada intercambio, así que actualiza ese archivo con un temporizador en shells de larga duración.

Verificar la configuración

Un intercambio exitoso devuelve un access_token que comienza con sk-ant-oat01- y un valor expires_in en segundos. Si el intercambio falla con la respuesta opaca 401 authentication_error (mensaje Authentication failed), revisa la página de historial de autenticación para ver el motivo de la denegación y consulta Solucionar un intercambio fallido; la causa más común del lado de Okta es una discrepancia en issuer_url (debe incluir la ruta /oauth2/<auth-server-id>; el servidor de autorización de la organización de Okta no se puede usar).

Delimitar el alcance de tu regla

Restringe el bloque match de la regla al alcance más estrecho que se ajuste a tu caso de uso:

• Fija el Client ID exacto: Establece subject_prefix en el Client ID completo de la aplicación de servicio, sin * al final.
• Fija la audiencia: Haz coincidir el valor audience que configuraste en el servidor de autorización para que se rechacen los tokens emitidos para una audiencia diferente.
• Haz coincidencias con claims personalizados: Para un alcance más granular, agrega claims en la pestaña Claims del servidor de autorización y hazlos coincidir con el mapa claims de la regla o una condition CEL.
• Usa una regla por aplicación de servicio: Crea una regla de federación independiente para cada aplicación de servicio en lugar de compartir una regla entre aplicaciones.

Próximos pasos

• Revisa la referencia de WIF para conocer el orden completo de resolución de credenciales y la configuración de perfiles.
• Consulta la referencia de WIF para hacer coincidencias con claims personalizados de Okta mediante expresiones CEL.