Configurazione degli account ISE Guest con l'API REST
Sommario
Introduzione
In questo documento viene descritto come utilizzare la funzionalità API REST (Representative State Transfer) per eseguire le attività relative ai guest in Identity Services Engine (ISE). Cisco Guest API è un set di operazioni basato su REST che fornisce accesso protetto HTTPS e autenticato per gestire gli utenti Cisco Guest. Con l'API è possibile creare, leggere, aggiornare, eliminare e cercare utenti guest.
Prerequisiti
Requisiti
Cisco raccomanda la conoscenza dei seguenti argomenti:
- ISE
- Servizi REST esterni
- Client REST come Insonnia, RESTED, ecc.
Componenti usati
Le informazioni fornite in questo documento si basano sulle seguenti versioni software e hardware:
- Cisco ISE, release 2.6
- Insonnia REST client v7.1.1
Le informazioni discusse in questo documento fanno riferimento a dispositivi usati in uno specifico ambiente di emulazione. Su tutti i dispositivi menzionati nel documento la configurazione è stata ripristinata ai valori predefiniti. Se la rete è operativa, valutare attentamente eventuali conseguenze derivanti dall'uso dei comandi.
Premesse
Per utilizzare l'API, è necessario configurare in ISE il servizio ERS (External RESTful Services) abilitato e l'autenticazione dello sponsor. ERS supporta l'autenticazione di base ed è eseguito sulla porta 9060. Le credenziali di autenticazione sono crittografate e fanno parte dell'intestazione della richiesta. ERS richiede all'amministratore ISE di assegnare privilegi speciali a un utente per eseguire le operazioni.
Il documento descrive i seguenti passaggi di configurazione:
1. Abilitare ERS su ISE
2. Impostare l'account amministratore e sponsor per ERS
3. Crea un account Guest
4. Leggi, aggiorna, elimina dati guest
Configurazione
Abilita ERS su ISE
Per utilizzare la funzione API REST su ISE, è necessario abilitare ERS.
Selezionare Amministrazione > Sistema > Impostazioni > Impostazioni ERS > Abilita ERS per la lettura/scrittura come mostrato nell'immagine.
Tutte le informazioni relative a ERS sono disponibili come Software Development Kit (SDK) sulla porta HTTPS 9060 di ISE. È possibile accedere a questa funzionalità dopo aver attivato ERS e aver eseguito l'accesso con un account admin con i privilegi di "ERS-Admin" o "ERS-Operator".
Configura account amministratore e sponsor per ERS
Per utilizzare ERS, ISE richiede un account admin con privilegi ERS-Admin o ERS-operator. È necessario creare e aggiungere account di amministrazione ai rispettivi gruppi. In alternativa, l'accesso ERS è valido anche per l'account Super-Admin.
Per utilizzare le API per le funzionalità guest, l'amministratore ERS richiede dati non elaborati dei portali, ad esempio l'ID del portale, i gruppi di identità guest e così via. Tuttavia, per leggere/creare/aggiornare o eliminare i dati guest, è necessario un account sponsor con accesso ERS abilitato.
- Ai fini del presente documento, viene usato un account utente ISE interno come sponsor.
- Passare a Amministrazione > Gestione delle identità > Identità e aggiungere un utente di accesso alla rete come mostrato nell'immagine.
- Questo account utente deve essere aggiunto a uno dei gruppi sponsor.
- L'account di esempio è mappato al gruppo sponsor predefinito denominato ALL_ACCOUNTS.
- Per consentire l'accesso ERS a questo gruppo sponsorizzato, passare a Centri di lavoro > Accesso guest > Portale e componenti > Gruppi di sponsor e aprire il gruppo di sponsor assegnato.
- Abilitare l'opzione:
Crea un account Guest
Per creare un account guest tramite API, è necessario che la chiamata API venga effettuata a ISE come sponsor e tramite un portale sponsorizzato riconosciuto da ISE.
Passaggio 1. Per recuperare gli ID portale di tutti i portali sponsor preconfigurati su ISE, usare un client REST con le informazioni fornite qui:
| Metodo | OTTIENI |
| URL | https://<ISE-IP>:9060/ers/config/sponsorportal |
| Credenziali | Usa credenziali amministratore ERS |
| Intestazioni | Content-Type: applicazione/xml Accetta: applicazione/xml |
Output previsto:
<?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>
Il valore di interesse è l'ID portale del portale Sponsor da utilizzare per creare utenti guest. In questo esempio, l'ID è "274a95f0-2e58-11e9-98fb-0050568775a3".
Passaggio 2. Utilizzare questa chiamata API per creare un account guest. Il valore di portalID è quello recuperato dal passaggio 1.
| Metodo | POST |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/ |
| Credenziali | Usa credenziali account sponsor |
| Intestazioni | Content-Type: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml Accetta: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml |
| Corpo |
<?xml version="1.0" encoding="UTF-8"?> |
Output previsto:
Passare a ISE GUI > Master GuestReport per verificare se l'account è stato creato:
Leggi, Aggiorna, Elimina dati guest
Di seguito sono riportate alcune chiamate API di esempio per eseguire varie azioni sui dati guest. Tutte le opzioni disponibili e i relativi formati sono disponibili nell'SDK.
- Ottieni i dettagli di un account utente guest per nome:
| Metodo | OTTIENI |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| Credenziali | Usa credenziali account sponsor |
| Intestazioni | Content-Type: applicazione/xml Accetta: applicazione/xml |
Output previsto:
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>
- Reimposta password utente guest:
È necessario innanzitutto recuperare l'ID guest dalla chiamata e quindi utilizzarlo in questa API. In questo esempio, l'ID utente guest è "3b967932-86f8-11ea-aafe-72889dc971d1".
| Metodo | PUT |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id} |
| Credenziali | Usa credenziali account sponsor |
| Intestazioni | Content-Type: applicazione/xml Accetta: applicazione/xml |
Questo metodo non consente di specificare la nuova password. ISE restituirà l'output con la nuova password generata automaticamente.
Output previsto:
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>
- Elimina un account Guest per nome:
| Metodo | ELIMINA |
| URL | https://<ISE-IP>:9060/ers/config/guestuser/name/{name} |
| Credenziali | Usa credenziali account sponsor |
| Intestazioni | Content-Type: applicazione/xml Accetta: applicazione/xml |
Output previsto:
Verifica
Attualmente non è disponibile una procedura di verifica per questa configurazione.
Risoluzione dei problemi
Le informazioni contenute in questa sezione permettono di risolvere i problemi relativi alla configurazione.
Alcuni errori comuni e le possibili cause:
- La creazione di un account guest non riesce con l'errore:
401 Unauthorized
<message type="ERROR" code="CRUD operation exception">
<title>Sponsor does not have permission to access REST Apis</title>
</message>
Risolto: Questo significa che l'account sponsor utilizzato per l'account guest è mappato a un gruppo sponsor in cui l'accesso ERS non è abilitato. Modificare il gruppo sponsor corrispondente e abilitare gli account Access Cisco ISE Guest usando l'interfaccia programmatica (API Guest REST).
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>
Risolto: L'ID portale immesso nella chiamata non esiste in ISE o non è corretto. Dalla chiamata "Get" per il portale sponsor, recuperare l'ID portale corretto del portale.
- Codici di risposta API e relativi significati possibili:
200 (OK): Indica che l'API REST ha eseguito l'azione desiderata.
201 (Creato): Indica che una risorsa è stata creata all'interno di una raccolta.
204 (nessun contenuto): Generalmente viene inviato come risposta a richieste PUT, POST o DELETE.
400 (Richiesta non valida): Codice di errore generico per problemi quali sintassi delle richieste non valida, parametri non validi e così via. Leggere i dettagli del messaggio, se disponibili, per comprendere la causa.
401 (non autorizzato): Ciò indica che l'azione è stata eseguita con credenziali errate, senza credenziali o che l'account non è autorizzato a eseguire l'azione.
500(Errore interno del server): Indica un problema sul lato server. L'accesso ad ISE può aiutare a capire la causa.
Per ulteriori informazioni sull'uso dell'API REST per ISE, fare riferimento all'API REST Guest.
Feedback