Contenu

Introduction

Conditions préalables

Conditions requises

Components Used

Informations générales

Configuration

Activer ERS sur ISE

Configurer le compte d'administrateur et de sponsor pour ERS

Créer un compte invité

Lire, Mettre à jour, Supprimer les données d'invité

Vérification

Dépannage

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.

Note: La procédure est similaire ou identique pour d'autres versions ISE. Vous pouvez utiliser ces étapes sur toutes les versions du logiciel ISE 2.x sauf indication contraire.

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 : Accédez aux comptes d'invité Cisco ISE à l'aide de l'interface de programmation (API REST invité), comme illustré dans l'image.

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 » ? >

<ns2:guestuser xmlns:ns2=« identity.ers.ise.cisco.com »>

<champs personnalisés>

</customFields>

<guestAccessInfo>

<fromDate>25/04/2020 18:55</fromDate>

<location>Delhi</location>

<toDate>28/04/2020 19:55</àDate>

<val.Days>3</val.Days>

</guestAccessInfo>

<guestInfo>

<company>Cisco</company>

<emailAddress>abcd@cisco.com</emailAddress>

<firstName>John</firstName>

<lastName>Doe</lastName>

<notificationLanguage>Anglais</notificationLanguage>

<password>9618</password>

<phoneNumber>999998877</phoneNumber>

<smsServiceProvider>Global Default</smsServiceProvider>

<userName>johndoe</userName>

</guestInfo>

<guestType>Contractant (valeur par défaut)</guestType>

<personnevisitée>abcd3@cisco.com</personnevisitée>

<portalId>274a95f0-2e58-11e9-98fb-0050568775a3</portalId>

<raisonForVisit>Visiter Bob à partir de la comptabilité</raisonForVisit>

</ns2 : utilisateur invité>

Note: Le contenu du corps affiché ici peut être utilisé comme modèle (disponible en SDK également). Assurez-vous que la date de début et la date correspond à un jour valide. L'emplacement, le type d'invité et d'autres valeurs doivent être valides en référence à l'ISE utilisée, mais l'appel échouera.

Note: Les informations d'identification utilisées lors de cet appel doivent être un compte de sponsor valide mappé à un groupe de sponsor. Les informations d'identification de l'administrateur ERS ici ne fonctionneront pas. Reportez-vous à la section précédente de ce guide pour plus de détails.

Résultats attendus :

Accédez à GUI ISE > Master GuestReport afin de vérifier si le compte a été créé :

Note: Il n'existe aucune option permettant de spécifier une combinaison de nom d'utilisateur et de mot de passe personnalisée par compte invité à partir d'un portail de sponsor. Cette méthode d'API peut être utilisée pour répondre à cette exigence.

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é.