Configurer les comptes d'invités ISE avec l'API REST
Contenu
Introduction
Ce document décrit comment utiliser la fonctionnalité API REST (Représentation State Transfer) pour effectuer des tâches liées aux invités sur le moteur ISE (Identity Services Engine). L'API Cisco Guest est un ensemble d'opérations REST qui fournit un accès HTTPS sécurisé et authentifié pour gérer les utilisateurs invités Cisco. Avec l'API, vous pouvez créer, lire, mettre à jour, supprimer et rechercher des utilisateurs invités.
Conditions préalables
Conditions requises
Cisco vous recommande de connaître ces sujets :
- ISE
- Services RESTful externes
- Clients REST comme Insomnie, RESTED, etc.
Components Used
Les informations contenues dans ce document sont basées sur les versions de matériel et de logiciel suivantes :
- Cisco ISE, version 2.6
- Client REST Insomnie v7.1.1
The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. Si votre réseau est en ligne, assurez-vous de bien comprendre l’incidence possible des commandes.
Informations générales
Pour utiliser l'API, l'authentification ERS (External RESTful Services) activée et de sponsor doit être configurée dans ISE. ERS prend en charge l'authentification de base et est exécuté sur le port 9060. Les informations d'identification d'authentification sont chiffrées et font partie de l'en-tête de demande. ERS exige que l'administrateur ISE attribue des privilèges spéciaux à un utilisateur pour effectuer des opérations.
Le document couvre les étapes de configuration suivantes :
1. Activer ERS sur ISE
2. Configurer le compte d'administrateur et de sponsor pour ERS
3. Créer un compte invité
4. Lire, mettre à jour, supprimer des données d'invité
Configuration
Activer ERS sur ISE
Pour pouvoir utiliser la fonctionnalité REST API sur ISE, ERS doit être activé.
Accédez à Administration > System > Settings > ERS settings > Enable ERS for read/write comme indiqué dans l'image.
Toutes les informations relatives à ERS sont disponibles en tant que Kit de développement logiciel (SDK) sur le port HTTPS 9060 d'ISE. Vous pouvez y accéder après avoir activé ERS et ouvert une session avec un compte d'administrateur avec les privilèges « ERS-Admin » ou « ERS-Operator ».
Configurer le compte d'administrateur et de sponsor pour ERS
Pour utiliser ERS, ISE nécessite un compte d'administrateur auquel sont affectés les privilèges ERS-Admin ou ERS-opérateur. Les comptes d'administration doivent être créés et ajoutés aux groupes respectifs. Sinon, l'accès ERS fonctionne également pour le compte Super-Admin.
Afin d'utiliser des API pour les fonctionnalités d'invité, l'administrateur ERS nécessite des données brutes des portails telles que l'ID du portail, les groupes d'identités d'invité, etc. Cependant, pour lire, créer, mettre à jour ou supprimer des données d'invité, un compte de sponsor avec accès ERS activé est requis.
- Pour les besoins de ce document, un compte utilisateur ISE interne est utilisé comme sponsor.
- Accédez à Administration > Identity Management > Identities et ajoutez un utilisateur d'accès au réseau comme illustré dans l'image.
- Ce compte d'utilisateur doit être ajouté à l'un des groupes de sponsor.
- Le compte d'exemple est mappé au groupe de sponsor par défaut nommé ALL_ACCOUNTS.
- Afin de permettre l'accès ERS pour ce groupe parrainé, allez à Centres de travail > Accès invité > Portail et composants > Groupes de parrainage et ouvrez le groupe de parrainage assigné.
- Activez l'option :
Créer un compte invité
Pour créer un compte invité via l'API, il est nécessaire que l'appel d'API soit passé à ISE en tant que sponsor et via un portail sponsorisé qu'il reconnaît.
Étape 1. Afin de récupérer les ID de portail de tous les portails de sponsor préconfigurés sur ISE, utilisez n'importe quel client REST avec les informations fournies ici :
| Méthode | GET |
| URL | https://<ISE-IP>:9060/ers/config/sponsor portal |
| Informations d'identification | Utiliser les informations d'identification de l'administrateur ERS |
| Header (En-tête) | Type de contenu : application/xml Accept (accepter): application/xml |
Résultats attendus :
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:searchResult total="1"
xmlns:ns5="ers.ise.cisco.com"
xmlns:ers-v2="ers-v2"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="v2.ers.ise.cisco.com">
<ns3:resources>
<ns5:resource description="Default portal used by sponsors to create and manage accounts for authorized visitors to securely access the network"
id="274a95f0-2e58-11e9-98fb-0050568775a3" name="Sponsor Portal (default)">
<link rel="self" href="https://10.127.197.186:9060/ers/config/sponsorportal/274a95f0-2e58-11e9-98fb-0050568775a3" type="application/xml"/>
</ns5:resource>
</ns3:resources>
</ns3:searchResult>
La valeur d'intérêt est l'ID de portail du portail Sponsor qui est destiné à être utilisé afin de créer des utilisateurs invités. L'ID est « 274a95f0-2e58-11e9-98fb-0050568775a3 » dans cet exemple.
Étape 2. Utilisez cet appel d'API afin de créer un compte d'invité. La valeur de portalID ici est celle récupérée à l'étape 1.
| Méthode | POST |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/ |
| Informations d'identification | Utiliser les informations d'identification du compte du sponsor |
| Header (En-tête) | Type de contenu : application/vnd.com.cisco.ise.identity.guestuser.2.0+xml Accept (accepter): application/vnd.com.cisco.ise.identity.guestuser.2.0+xml |
| Body (Corps) |
< ? xml version=« 1.0 » coding=« UTF-8 » ? > |
Résultats attendus :
Accédez à GUI ISE > Master GuestReport afin de vérifier si le compte a été créé :
Lire, Mettre à jour, Supprimer les données d'invité
Voici quelques exemples d'appels API pour effectuer diverses actions sur les données d'invité. Toutes les options disponibles et leurs formats sont disponibles dans le SDK.
- Obtenir les détails d'un compte d'utilisateur invité par nom :
| Méthode | GET |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| Informations d'identification | Utiliser les informations d'identification du compte du sponsor |
| Header (En-tête) | Type de contenu : application/xml Accept (accepter): application/xml |
Résultats attendus :
200 OK
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns4:guestuser id="3b967932-86f8-11ea-aafe-72889dc971d1" name="johndoe"
xmlns:ers="ers.ise.cisco.com"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns4="identity.ers.ise.cisco.com">
<link rel="self" href="https://10.127.197.186:9060/ers/config/guestuser/name/johndoe" type="application/xml"/>
<customFields/>
<guestAccessInfo>
<fromDate>04/25/2020 18:55</fromDate>
<location>Delhi</location>
<toDate>04/28/2020 19:55</toDate>
<validDays>3</validDays>
</guestAccessInfo>
<guestInfo>
<company>Cisco</company>
<creationTime>04/25/2020 18:55</creationTime>
<emailAddress>abcd@cisco.com</emailAddress>
<enabled>false</enabled>
<firstName>John</firstName>
<lastName>Doe</lastName>
<notificationLanguage>English</notificationLanguage>
<password>9618</password>
<phoneNumber>9999998877</phoneNumber>
<smsServiceProvider>Global Default</smsServiceProvider>
<userName>johndoe</userName>
</guestInfo>
<guestType>Contractor (default)</guestType>
<personBeingVisited>abcd3@cisco.com</personBeingVisited>
<reasonForVisit>Visiting Bob from Accounting</reasonForVisit>
<sponsorUserId>1f7627f0-86f8-11ea-aafe-72889dc971d1</sponsorUserId>
<sponsorUserName>Sponsor_ERS</sponsorUserName>
<status>AWAITING_INITIAL_LOGIN</status>
</ns4:guestuser>
- Réinitialiser un mot de passe utilisateur invité :
Cela nécessite d'abord de récupérer l'ID invité de l'appel, puis de l'utiliser dans cette API. L'ID utilisateur invité est « 3b967932-86f8-11ea-afe-72889dc971d1 » dans cet exemple.
| Méthode | PUT |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id} |
| Informations d'identification | Utiliser les informations d'identification du compte du sponsor |
| Header (En-tête) | Type de contenu : application/xml Accept (accepter): application/xml |
Cette méthode ne permet pas de spécifier le nouveau mot de passe. ISE renvoie le résultat avec le nouveau mot de passe généré automatiquement.
Résultat attendu :
200 OK
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<ns3:operationResult
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:ns3="ers.ise.cisco.com">
<attributesList>
<attribute name="password" value="2557"/>
</attributesList>
</ns3:operationResult>
- Supprimer un compte invité par son nom :
| Méthode | DELETE |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| Informations d'identification | Utiliser les informations d'identification du compte du sponsor |
| Header (En-tête) | Type de contenu : application/xml Accept (accepter): application/xml |
Résultat attendu :
Vérification
Aucune procédure de vérification n'est disponible pour cette configuration.
Dépannage
Cette section fournit des informations que vous pouvez utiliser pour dépanner votre configuration.
Quelques erreurs courantes et leurs causes possibles :
- La création d'un compte invité échoue avec une erreur :
401 Unauthorized
<message type="ERROR" code="CRUD operation exception">
<title>Sponsor does not have permission to access REST Apis</title>
</message>
Régler: Cela signifie que le compte de sponsor utilisé pour établir le compte invité est mappé à un groupe de sponsor où l'accès ERS n'est pas activé. Modifiez le groupe de sponsor qui correspond à cela et activez Access Cisco ISE guest account à l'aide de l'interface de programmation (Guest REST API).
400 Bad Request
<message type="ERROR" code="CRUD operation exception">
<title>Creating GuestUser failed due to com.cisco.cpm.guestaccess.validation.GuestAccessValidationException: Portal not found for portal session e1fc15a7-a170-4d6a-b02c-0ab7b0bc54ff</title>
Régler: L'ID de portail saisi dans l'appel n'existe pas sur ISE ou est incorrect. À partir de l'appel 'Get' pour le portail de sponsor, récupérez l'ID de portail correct du portail.
- Codes de réponse API et leurs significations possibles :
200 (OK) : Indique que l'API REST a réussi l'action souhaitée.
201 (Créé) : Indique qu'une ressource a été créée dans une collection.
204 (Pas de contenu) : Ceci est généralement envoyé en réponse aux requêtes PUT, POST ou DELETE.
400 (Requête incorrecte) : Code d'erreur générique pour les problèmes tels que la syntaxe de requête incorrecte, les paramètres non valides, etc. Lisez les détails du message si disponibles pour comprendre la cause.
401 (Non autorisé) : Cela indique que l'action a été entreprise avec des informations d'identification erronées, aucune information d'identification ou que le compte n'est pas autorisé à effectuer cette action.
500 (Erreur interne du serveur) : Indique un problème côté serveur. Les connexions sur ISE peuvent aider à comprendre la cause.
Pour plus de détails sur l'utilisation de l'API REST pour ISE, référez-vous à API REST invité.
CommentairesContacter Cisco
- Ouvrir un dossier d’assistance
- (Un contrat de service de Cisco est requis)