Utiliser WIF avec Okta

Utiliser WIF avec Okta - Claude API Docs

Okta peut agir en tant que fournisseur d'identité de charge de travail en émettant des jetons d'accès OIDC à une application de service via le grant OAuth 2.0 client_credentials. Votre charge de travail s'authentifie auprès d'Okta (généralement avec private_key_jwt, de sorte qu'aucun secret partagé n'est stocké), reçoit un « JSON Web Token » (jeton web JSON), ou JWT, signé, puis échange ce JWT auprès d'Anthropic contre un jeton d'accès de courte durée.

L'URL de l'émetteur du serveur d'autorisation Okta prend la forme https://<your-domain>.okta.com/oauth2/<auth-server-id>. Si vous utilisez le serveur par défaut intégré, le chemin est /oauth2/default.

Vous devez utiliser un serveur d'autorisation personnalisé Okta (y compris celui nommé default). Les jetons émis directement par le serveur d'autorisation de l'organisation Okta (le point de terminaison /oauth2/v1/token sans identifiant de serveur d'autorisation dans le chemin) ne peuvent pas être validés par des parties externes, car Okta ne publie pas de clés de signature pour ceux-ci.

Il existe de nombreuses façons de configurer Okta et de s'y authentifier qui sortent du cadre de cette documentation. Assurez-vous que votre configuration et vos mécanismes d'authentification respectent les directives et les pratiques de sécurité de votre entreprise.

Prérequis

Familiarité avec les concepts WIF : comptes de service, émetteurs de fédération et règles de fédération.
Une organisation Okta avec API Access Management activé (requis pour les serveurs d'autorisation personnalisés).
L'autorisation de créer des comptes de service, des émetteurs de fédération et des règles de fédération dans la Claude Console pour votre organisation Anthropic.
Une charge de travail capable de demander un jeton au point de terminaison /v1/token d'Okta et d'atteindre api.anthropic.com.

Configurer Okta

À un niveau général, vous devez :

Créer une application de service Okta.
Configurer votre serveur d'autorisation par défaut (ou créer un nouveau serveur d'autorisation personnalisé) avec une audience, un scope, une politique d'accès et toutes les revendications personnalisées sur lesquelles vous souhaitez établir une correspondance.

La navigation exacte dépend de la configuration de votre organisation Okta et de la version de la console d'administration. Les étapes numérotées ci-dessous décrivent un parcours courant :

Créez une intégration d'application de service. Dans la console d'administration Okta, créez une nouvelle intégration d'application de type API Services (OIDC, machine à machine). Notez le Client ID généré.
Configurez l'authentification du client. Pour une configuration sans clé, choisissez Public key / Private key (private_key_jwt) et enregistrez la JWK publique de votre charge de travail. Vous pouvez également utiliser un secret client si votre environnement peut en stocker un de manière sécurisée. Pour l'exemple suivant, vous devrez peut-être désactiver l'exigence DPoP sur l'application ; assurez-vous que votre configuration de production respecte les exigences de sécurité de votre organisation.
Définissez l'audience. Sur votre serveur d'autorisation personnalisé, définissez l'audience sur https://api.anthropic.com afin que les jetons d'accès émis portent cette revendication aud. Anthropic valide aud par rapport à cette valeur fixe.
Accordez un scope. Sur votre serveur d'autorisation personnalisé, assurez-vous qu'au moins un scope existe et que l'application de service est autorisée à le demander (par exemple, anthropic.access). Okta rejette les requêtes client_credentials qui n'incluent pas un scope accordé.

Pour une application de service utilisant client_credentials, Okta définit la revendication sub du jeton d'accès émis sur le Client ID de l'application, et iss sur l'URL de l'émetteur du serveur d'autorisation.

Configurer Anthropic

Suivez le guide de configuration pour enregistrer un émetteur de fédération, créer un compte de service Anthropic et créer une règle de fédération dans la Claude Console. Utilisez ces valeurs spécifiques à Okta.

Émetteur de fédération : Utilisez l'URL de votre serveur d'autorisation personnalisé Okta et le mode découverte. Anthropic lit le document de découverte .well-known/openid-configuration d'Okta et récupère le JWKS à partir du jwks_uri qu'il annonce.

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

Règle de fédération : Établissez une correspondance sur la revendication Okta sub, qui est le Client ID de l'application de service. Si vous avez défini des revendications personnalisées dans Okta, vous pouvez établir une correspondance sur celles-ci à la place avec la map claims ou une 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
}

Acquérir un jeton et appeler l'API Claude

Contrairement aux fournisseurs natifs de plateforme (AWS, Google Cloud, Kubernetes), qui rendent un jeton disponible dans l'environnement d'exécution de la charge de travail (via un fichier projeté ou un point de terminaison de métadonnées local), Okta ne le fait pas. Votre charge de travail doit appeler le point de terminaison de jeton d'Okta pour obtenir un JWT, puis transmettre ce JWT au SDK Anthropic en tant que jeton d'identité.

Chaque onglet de SDK illustre le modèle appelable : le SDK Anthropic rappelle votre fournisseur de jeton d'identité chaque fois que le jeton d'accès Anthropic approche de son expiration, de sorte que votre récupérateur Okta doit renvoyer un jeton frais à chaque appel plutôt que d'en mettre un en cache indéfiniment. La CLI ant relit ANTHROPIC_IDENTITY_TOKEN_FILE à chaque échange, donc actualisez ce fichier à intervalles réguliers pour les shells de longue durée.

Vérifier la configuration

Un échange réussi renvoie un access_token commençant par sk-ant-oat01- et une valeur expires_in en secondes. En cas de 400 invalid_grant, consultez Dépanner un échange échoué ; la cause la plus courante côté Okta est une incohérence de issuer_url (elle doit inclure le chemin /oauth2/<auth-server-id> ; le serveur d'autorisation de l'organisation Okta n'est pas utilisable).

Délimiter votre règle

Plusieurs applications de service sous le même serveur d'autorisation Okta partagent le même émetteur. Une règle qui omet subject_prefix correspond à toutes les applications de service sur ce serveur, de sorte que toute équipe pouvant en enregistrer une pourrait obtenir un jeton Anthropic fédéré.

Verrouillez le bloc match de la règle sur la portée la plus étroite qui convient à votre cas d'usage :

Épinglez le Client ID exact : Définissez subject_prefix sur le Client ID complet de l'application de service sans * final.
Épinglez l'audience : Établissez une correspondance sur la valeur audience que vous avez configurée sur le serveur d'autorisation afin que les jetons émis pour une audience différente soient rejetés.
Établissez une correspondance sur des revendications personnalisées : Pour une délimitation plus fine, ajoutez des revendications dans l'onglet Claims du serveur d'autorisation et établissez une correspondance avec la map claims de la règle ou une condition CEL.
Utilisez une règle par application de service : Créez une règle de fédération distincte pour chaque application de service plutôt que de partager une règle entre plusieurs applications.

Étapes suivantes

Consultez la référence WIF pour l'ordre complet de résolution des identifiants et la configuration des profils.
Consultez la référence WIF pour établir une correspondance sur des revendications Okta personnalisées avec des expressions CEL.

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",
            # Construisez le JWT client_assertion RFC 7523 signé avec la clé privée de votre application 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)