Cet article est un guide complet destiné aux administrateurs de Netskope qui migrent les intégrations API du modèle de jeton REST API V2 vers le cadre de compte de service RBAC V3 sécurisé et axé sur les rôles.
Cette migration est une étape cruciale, car le cadre RBAC V3 représente un changement architectural obligatoire vers un système décentralisé, “API First” architecture, garantissant une autorisation cohérente pour les interactions de l'interface WebUI et de l'API REST.
Déprogrammation des jetons de la V2 de l'API REST et flux de travail du compte de service obligatoire
L'ancien workflow de provisionnement des jetons de l'API REST V2 est obsolète et ne sera plus disponible après l'activation de la fonctionnalité RBAC V3.
- V2 Token Deprecation Status: Vous ne pouvez plus fournir les jetons New V2 à l'aide de l'interface obsolète (Settings > Tools > Rest API V2) une fois que RBAC V3 est activé.
- Existing V2 Tokens: Tous les jetons V2 existants continueront de fonctionner jusqu’à leur date d’expiration spécifiée. Cependant, ces jetons cannot be extended.
- New Workflow Requirement: Tous les futurs approvisionnements en jetons doivent être effectués à l'aide du processus de création de compte de service New, qui est entièrement intégré au cadre de gestion des rôles RBAC V3.
Audit proactif des clients API (étape critique préalable à la mise en œuvre)
Avant d'activer les listes d'autorisation d'IP pour un rôle New RBAC V3 ou globalement, les administrateurs must effectuent un audit proactif de toutes les IP sources des clients API. C'est le seul moyen d'éviter une panne de service catastrophique.
L'activation d'une liste d'autorisation IP globale ou basée sur les rôles sans un inventaire complet des clients API existants peut entraîner un problème de sécurité. “self-inflicted denial-of-service attack.”
L'activation de la liste d'autorisation bloque instantanément tous les appels d'API provenant d'IP non répertoriées, ce qui interrompt les intégrations opérationnelles et de sécurité critiques, notamment :
- Plateformes de gestion des informations et des événements de sécurité (SIEM) enregistrant les journaux.
- Outils d'orchestration, d'automatisation et de réponse en matière de sécurité (SOAR) permettant d'orchestrer les réponses.
- Flux d'approvisionnement des utilisateurs du SCIM
- Scripts personnalisés et outils d'établissement de rapports automatisés
Utilisation de l'API REST pour l'inventaire IP
La méthode définitive et la source de vérité la plus fiable pour l'activité administrative de l'API est la V2 de l'API REST de Netskope elle-même, et non le journal d'audit de l'interface utilisateur.
Étape 1 : Déterminer l'étendue de l'audit
- Recommended Audit Window: Utilisez un minimum de 90-day audit window. Cette période correspond à la durée de conservation des journaux par défaut de Netskope et garantit la capture des activités API fréquentes et peu fréquentes.
- Required Endpoints: Interrogez les points de terminaison
datasearchde l'API REST v2, conçus pour les requêtes ad hoc, en vous concentrant sur les événements les plus susceptibles de contenir une activité API :
◦ /api/v2/events/datasearch/alert
◦ /api/v2/events/datasearch/application
◦ /api/v2/events/datasearch/page
- Key Data Point: Extraire la valeur du champ srcip à partir des enregistrements de journal retournés, car cela contient l’adresse IP source du client API.
Étape 2 : Extraction de l'inventaire à l'aide d'un script (exemple)
Pour gérer efficacement la pagination et traiter le grand volume de données, il est nécessaire de recourir à l'interrogation programmatique.
La tâche principale consiste à interroger par programme ces journaux d'événements, à extraire le site srcip et à agréger une liste finale et unique de toutes les adresses IP sources.
Example Implementation Logic:
- Le script doit parcourir les points de terminaison
datasearchdéfinis pour la période de 90 jours. - Il doit traiter pagination en incrémentant le paramètre
offsetjusqu'à ce qu'il n'y ait plus d'enregistrements renvoyés. - Il doit analyser la réponse JSON et en extraire les valeurs uniques
srcip, pour finalement fournir une liste exhaustive de toutes les IP sources des clients.
Étape 3 : Mise en œuvre de la liste d'autorisations basée sur les rôles
- Review and Approve: La liste agrégée des adresses IP uniques doit être examinée afin d'établir une corrélation entre chaque IP, son propriétaire et son objectif (par exemple, plate-forme SIEM, outil personnalisé).
- Configure Role Allowlist: Naviguez dans les paramètres de rôle (Paramètres > Administration > Rôles) et remplissez la section IP Allowlist avec les adresses IPv4 approuvées.
◦ Les adresses IP doivent être space-delimited et être des adresses IPv4 valides.
- Critical Security Note: La liste blanche d'adresses IP basée sur les rôles supersedes and overrides tous les paramètres de liste blanche d'adresses IP globales précédemment configurés. Si cette option est activée pour ce rôle, elle devient la seule source de vérité pour le contrôle d'accès de ce compte de service.
Mise à jour de l'intégration SCIM : Migration pas à pas vers Service Account V3
La migration d'un jeton API hérité vers un compte de service New RBAC V3 nécessite un processus séquentiel en trois parties : Création du rôle, Création du compte de service et Mise à jour de l'intégration.
Étape 1 : Création d'un rôle (principe du moindre privilège)
Comme RBAC V3 est axé sur les rôles, vous devez vous rendre sur le site create the role first avant de créer le compte de service.
- Navigate to Role Management: Allez à Administration > Roles et cliquez sur New.
- Define Permissions (PoLP): Attribuer un nom descriptif (par exemple,
scim_provisioner). Appliquez le Principle of Least Privilege (PoLP).
◦ Pour SCIM, sélectionnez la catégorie Administration.
◦ Explicitement deselect permissions for UI functions et toute autre opération non essentielle, car les comptes de service ne sont pas interactifs.
◦ Définissez le niveau d'autorisation sur Manage pour les API Users et Group, car elles sont nécessaires pour le provisionnement du SCIM.
- Apply IP Allowlist: Si vous avez effectué l’audit (Section 2), allez à l’onglet IP Allowlist et ajoutez les adresses IPv4 source approuvées de votre fournisseur d’identité (IdP).
Étape 2 : Création d'un compte de service et d'un jeton
- Create Service Account: Accédez à Administration > Administrators & Roles et cliquez sur Service Account.
- Configure Account: Tapez le nom du compte service et sélectionnez le rôle personnalisé créé à la Phase A (par exemple,
scim_provisioner). - Set Expiration: Specify the token’s expiration period (e.g., 12 months).
- Generate and Store Token (Critical Step): Cliquez Create. Le jeton API est affiché only once lors de la création réussie. Il est critical to copy and securely store this token immediately car il ne peut pas être récupéré plus tard.
Étape 3 : Mise à jour de l'intégration du SCIM
- Update API Token: Dans les paramètres de provisionnement SCIM de votre fournisseur d’identité (IdP) (par exemple, Okta ou Entra ID), remplacez l’ancien jeton API V2 par le new V3 Service Account token.
- Update Base URL: L'ancienne URL du service SCIM est obsolète et doit être modifiée pour pointer vers le point de terminaison conforme à New RBAC V3.
◦ New Base URL Format: https://<tenant-name>.goskope.com/api/v2/scim.
- Test Connection: Après avoir mis à jour à la fois le jeton et l’URL de base, test the connection de s’assurer que l’intégration fonctionne correctement.
Dépannage des erreurs de connexion
Si le test de connexion échoue, la raison la plus fréquente est un conflit avec la liste d'autorisations IP basée sur les rôles.
- Verify Source IPs: Vérifiez la configuration de la liste blanche IP du rôle pour vous assurer que les adresses IP sources actuelles utilisées par votre fournisseur SCIM spécifique (par exemple, les adresses IP des cellules Okta ou les plages d'identifiants Microsoft Entra) sont correctement incluses dans la liste blanche du rôle. N'oubliez pas que the role-based allowlist supersedes any global settings.