Configuration de l'intégration Okta

Présentation

Okta peut fournir des données normalisées sur le cycle de vie des utilisateurs, l’authentification, la MFA et l’activité administrative. Voici quelques exemples examinés :

account.locked — compte verrouillé
mfa.factor.activated — active des facteurs MFA supplémentaires
auth.login.failed — échoue à se connecter

Les deux méthodes de connexion lisent les deux mêmes flux : l’annuaire des utilisateurs (/api/v1/users) et le journal système (/api/v1/logs). Consultez comment les données d’intégration deviennent des signaux.

Choisir une méthode de connexion

	Okta (SSWS)	Okta (OAuth 2.0)
Identifiant	Un jeton d’API que vous créez dans la console d’administration	Un ID client et une clé JWK privée que vous générez et enregistrez
Configuration	Trois étapes, aucun matériel de clé à générer	Neuf étapes, dont une paire de clés RSA
Rôle d’administrateur requis	Administrateur en lecture seule, attribué au propriétaire du jeton	Administrateur en lecture seule, attribué à l’application
Durée de vie du jeton	Désactivé après 30 jours sans utilisation	Aucune expiration ; la rotation de la paire de clés vous incombe
À utiliser quand	Il s’agit de la méthode recommandée pour la plupart des organisations	Votre politique de sécurité interdit les jetons d’API de longue durée

Les deux méthodes nécessitent les mêmes accès ; le choix porte donc sur la gestion des identifiants, et non sur ce que la plateforme peut lire.

Option A — Jeton d’API (SSWS)

Recommandé.

Ce dont Living Security a besoin

Identifiant	Description
Clé API	Un jeton d’API Okta. La boîte de dialogue de connexion nomme ce champ Clé API
Sous-domaine du tenant	Le `<tenant>` dans `<tenant>.okta.com` — uniquement le sous-domaine, et non l’URL complète

Prérequis

Vous devez être Super Administrator Okta pour créer un utilisateur de compte de service, attribuer des rôles d’administrateur et créer des jetons d’API.

Créer un utilisateur propriétaire du jeton

Un jeton d’API Okta hérite des autorisations de l’utilisateur qui l’a créé et cesse de fonctionner si cet utilisateur est désactivé. Créez un compte de service dédié plutôt que d’utiliser un compte administrateur personnel, afin que la connexion survive aux changements de personnel.

Dans la console d’administration, accédez à Directory → People.
Cliquez sur Add person et créez un utilisateur tel que svc-livingsecurity@yourcompany.com.
Activez le compte.

Attribuer le rôle d'administrateur en lecture seule

La plateforme effectue uniquement des lectures. Accorder plus que l’accès en lecture donne au jeton des autorisations qu’il n’utilisera jamais.

Accédez à Security → Administrators.
Cliquez sur Add administrator et sélectionnez l’utilisateur de l’étape précédente.
Attribuez le rôle Read-only Administrator.
Enregistrez.

Sans rôle d’administrateur, les appels à l’API Okta Management réussissent avec 200 OK et renvoient une liste vide. Aucun 403 ne vous indique que le rôle est manquant : les flux restent simplement vides.

Créer le jeton d'API

Connectez-vous à la console d’administration en tant qu’utilisateur du compte de service de l’étape 1. Le jeton hérite des droits du compte qui le crée.
Accédez à Security → API et ouvrez l’onglet Tokens.
Cliquez sur Create token, donnez-lui un nom tel que Living Security Platform, puis cliquez sur Create token.
Copiez la valeur du jeton maintenant : Okta ne l’affiche qu’une seule fois.

Okta désactive un jeton d’API après 30 jours sans utilisation. Les synchronisations de cette intégration s’exécutent au moins une fois par jour ; une connexion active maintient donc son propre jeton actif. Une connexion laissée en pause pendant un mois nécessite un nouveau jeton.

La liste d’adresses ci-dessus n’est pertinente que si votre organisation Okta restreint l’accès à l’API par zone réseau. C’est rarement le cas.

Trouver le sous-domaine de votre tenant

L’URL de votre console d’administration ressemble à https://acme-admin.okta.com. Le sous-domaine du tenant est acme — sans le suffixe -admin, sans .okta.com et sans https://.

Vous êtes maintenant connecté à Okta (SSWS).

Dépannage

401 Unauthorized

Le jeton est invalide, a été révoqué ou a été désactivé après 30 jours d’inactivité. Créez un nouveau jeton en tant qu’utilisateur du compte de service et saisissez-le à nouveau dans la connexion.

Connecté, mais tous les flux sont vides

Le propriétaire du jeton n’a aucun rôle d’administrateur. Attribuez Read-only Administrator au compte de service (étape 2) : l’API renvoie 200 OK avec une liste vide, plutôt qu’une erreur, lorsque le rôle est manquant.

Les synchronisations échouent après un changement de personnel

Le jeton cesse de fonctionner si l’utilisateur qui l’a créé est désactivé. C’est pourquoi le jeton doit appartenir à un compte de service et non à une personne.

Option B — Application de service OAuth 2.0

Utilisez cette méthode lorsque votre politique de sécurité n’autorise pas les jetons d’API de longue durée. Elle remplace le jeton par un ID client et une paire de clés RSA dont vous êtes propriétaire. Dans la plateforme, il s’agit de la vignette Okta (OAuth 2.0), sous Paramètres → Intégrations → Catalogue. Pour vous authentifier auprès d’Okta à l’aide de Client Credentials, vous avez besoin des éléments suivants :

ID client - Un identifiant unique pour votre application Okta API Services.
Clé privée (JWK) - La clé privée RSA au format JSON Web Key, dont la clé publique est enregistrée dans votre application Okta.
Domaine Okta - Uniquement le sous-domaine de votre tenant Okta (par ex. dev-12345678), et non le nom d’hôte complet.
Portées - Une liste, séparée par des espaces, de portées de l’API Okta Management (par ex. okta.users.read okta.logs.read).

Ce guide vous explique comment créer une application API Services dans Okta avec l’authentification private_key_jwt.

Prérequis :

Vous devez disposer d’un compte Okta. Créez un compte développeur gratuit sur developer.okta.com.

Étape 1 : Création de votre application Okta API Services

Connectez-vous à votre console d’administration Okta.
Dans la barre latérale gauche, accédez à Applications > Applications.
Cliquez sur Create App Integration.
Sélectionnez API Services comme méthode de connexion, puis cliquez sur Suivant.

Donnez un nom à votre application, puis cliquez sur Sauvegarder.
Dans l’onglet General de l’application, repérez votre ID client : vous en aurez besoin à la dernière étape.
Définissez Client authentication sur Public key / Private key. Les portées okta.* ne sont prises en charge qu’avec cette méthode d’authentification.

Désactivez Proof of possession (DPoP) : cette option n’est pas prise en charge.

L’application doit être créée en tant que API Services.

Étape 2 : Génération et enregistrement de votre paire de clés RSA

Utiliser le générateur de clés d’Okta

Okta peut générer la paire de clés RSA pour vous directement dans la console d’administration :

Dans la console d’administration, ouvrez votre application API Services.
Accédez à l’onglet General et faites défiler jusqu’à la section PUBLIC KEYS.
Cliquez sur Add Key, puis sélectionnez Generate new key.
Cliquez sur Sauvegarder : Okta génère la paire de clés et affiche la clé privée (JWK) une seule fois.
Copiez et enregistrez immédiatement le JSON de la clé privée : il ne sera plus affiché.

La clé publique est automatiquement enregistrée auprès de votre application.

Copiez la clé JWK privée avant de fermer la boîte de dialogue. Collez-la dans le champ Private Key de la Living Security Platform à la dernière étape.

Créer votre propre clé

Okta utilise private_key_jwt pour les applications API Services. Vous générez une paire de clés RSA, enregistrez la clé JWK publique auprès d’Okta et fournissez la clé JWK privée à la Living Security Platform. Générez une clé JWK privée à l’aide du script Node.js suivant (Node.js 18 ou version ultérieure requis) :

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

Enregistrez la clé JWK publique dans Okta :

Dans la console d’administration, ouvrez votre application API Services.
Accédez à l’onglet General et faites défiler jusqu’à la section PUBLIC KEYS.
Cliquez sur Add Key, collez le JSON de la clé JWK publique produit par le script ci-dessus, puis cliquez sur Sauvegarder.

La clé JWK privée est celle que vous collez dans la Living Security Platform. Elle contient tout le matériel de clé (d, p, q, dp, dq, qi) ainsi que kid. Gardez-la secrète.

Étape 3 : Trouver votre domaine Okta

Saisissez uniquement le sous-domaine de votre tenant Okta, c’est-à-dire la partie située avant .okta.com.

Dans la console d’administration, la barre d’adresse de votre navigateur affiche une URL telle que https://dev-12345678-admin.okta.com.
Votre domaine Okta est uniquement le sous-domaine (par ex. dev-12345678), et non dev-12345678.okta.com.
Vous pouvez également accéder à Paramètres > Account dans la console d’administration pour trouver votre domaine Okta, puis utiliser la partie correspondant au sous-domaine.

Étape 4 : Accorder des portées d’API à votre application

Okta exige au moins une portée dans chaque demande de jeton. Avant que votre application puisse demander des portées spécifiques, celles-ci doivent être accordées :

Dans la console d’administration, accédez à Applications > Applications et ouvrez votre application.
Cliquez sur l’onglet Okta API Scopes.
Accordez les portées requises par votre intégration : okta.users.read et okta.logs.read.

Une liste complète des portées disponibles figure dans la référence de l’API Okta Management.

Étape 5 : Attribuer un rôle d’administrateur à votre application

Accorder des portées ne suffit pas : les points de terminaison de l’API Okta Management (par ex. /api/v1/users) renvoient silencieusement une réponse 200 [] vide si votre application n’a aucun rôle d’administrateur. Vous devez attribuer au minimum Read-Only Administrator :

Dans la console d’administration, accédez à Security > Administrators (ou à Applications > Applications > votre application > Admin roles).
Cliquez sur Add administrator assignment et sélectionnez votre application API Services.

Attribuez le rôle Read-Only Administrator (ou un rôle supérieur, selon les portées dont vous avez besoin).
Cliquez sur Sauvegarder.

Sans rôle d’administrateur, les appels d’API réussissent avec 200 OK mais renvoient des résultats vides, et aucune erreur 403 n’indique le problème.

Étape 6 : Saisir les identifiants dans la Living Security Platform

Une fois que vous disposez de votre ID client, de votre clé privée (JWK), de votre domaine Okta et de vos portées :

Ouvrez le formulaire dans lequel vous devez vous authentifier auprès d’Okta (Client Credentials).
Saisissez votre ID client.
Collez votre clé privée (JWK) : l’objet JSON complet produit par le script ci-dessus (sur une seule ligne ou mis en forme).
Saisissez votre domaine Okta en indiquant uniquement le sous-domaine du tenant (par ex. dev-12345678).
Saisissez les portées sous forme de liste séparée par des espaces (par ex. okta.users.read okta.logs.read).
Envoyez le formulaire ; vous devriez être authentifié avec succès.

Vous êtes maintenant connecté à Okta (Client Credentials).

Certaines parties de cette documentation sont adaptées de Nango, utilisée sous la licence Elastic License 2.0.

Intégrations

Configuration des intégrations

Catalogue

Canaux sortants

Présentation

Choisir une méthode de connexion