Sommario

Introduzione

Prerequisiti

Requisiti

Componenti usati

Premesse

Configurazione

Abilita ERS su ISE

Configura account amministratore e sponsor per ERS

Crea un account Guest

Leggi, Aggiorna, Elimina dati guest

Verifica

Risoluzione dei problemi

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.

Nota: La procedura è simile o identica per altre versioni ISE. Se non specificato diversamente, è possibile eseguire la procedura seguente su tutte le versioni software ISE 2.x.

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: Accedere agli account guest di Cisco ISE utilizzando l'interfaccia programmatica (API Guest REST), come mostrato nell'immagine.

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

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

<CampiPersonalizzati>

</customFields>

<InformazioniAccessoGuest>

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

<location>Delhi</location>

<toDate>28/04/2020 19.55</toDate>

<validDays>3</validDays>

</guestAccessInfo>

<InformazioniGuest>

<company>Cisco</company>

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

<firstName>Mario</firstName>

<lastName>Fatto</lastName>

<notificationLanguage>Inglese</notificationLanguage>

<password>9618</password>

<phoneNumber>999998877</phoneNumber>

<smsServiceProvider>Predefinito globale</smsServiceProvider>

<userName>mezzanotte</userName>

</guestInfo>

<guestType>Appaltatore (predefinito)</guestType>

<personBeingVisited>abcd3@cisco.com</personBeingVisited>

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

<reasonForVisit>Visita di Bob dall'ufficio contabilità</reasonForVisit>

</ns2:utenteguest>

Nota: Il contenuto del corpo visualizzato qui può essere utilizzato come modello (disponibile anche in SDK). Verificare che fromDate, toDate corrisponda a validDays. La località, il tipo di ospite e altri valori devono essere validi in riferimento all'ISE utilizzato, solo in questo caso la chiamata avrà esito positivo.

Nota: Le credenziali utilizzate per questa chiamata devono essere un account sponsor valido mappato a un gruppo sponsor. Le credenziali dell'amministratore ERS qui non funzioneranno. Fare riferimento alla sezione precedente di questa guida per ulteriori dettagli.

Output previsto:

Passare a ISE GUI > Master GuestReport per verificare se l'account è stato creato:

Nota: Non è possibile specificare una combinazione personalizzata di nome utente e password per account guest da un portale sponsor. Questo metodo API può essere utilizzato per soddisfare tale requisito.

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.