Konfigurieren von ISE-Gastkonten mit REST-API

Einführung

In diesem Dokument wird beschrieben, wie die REST-API-Funktion (Representational State Transfer) zum Ausführen von Gastaufgaben auf der Identity Services Engine (ISE) verwendet wird. Die Cisco Guest API ist ein REST-basierter Satz von Operationen, der sichere HTTPS-Verbindungen und authentifizierten Zugriff für die Verwaltung von Cisco Gastbenutzern bietet. Mithilfe der API kann man Gastbenutzer erstellen, lesen, aktualisieren, löschen und suchen.

Voraussetzungen

Anforderungen

Cisco empfiehlt, über die folgenden Themen zu verfügen:

• ISE
• Externe RESTful-Services
• REST-Clients wie Schlaflosigkeit, RESTED usw.

Verwendete Komponenten

Die Informationen in diesem Dokument basieren auf den folgenden Software- und Hardwareversionen:

• Cisco ISE, Version 2.6
• Insomnia REST Client v7.1.1

Die Informationen in diesem Dokument wurden von den Geräten in einer bestimmten Laborumgebung erstellt. Alle in diesem Dokument verwendeten Geräte haben mit einer leeren (Standard-)Konfiguration begonnen. Wenn Ihr Netzwerk in Betrieb ist, stellen Sie sicher, dass Sie die potenziellen Auswirkungen eines Befehls verstehen.

Hinweis: Die Vorgehensweise ist für andere ISE-Versionen ähnlich oder identisch. Sofern nicht anders angegeben, können Sie diese Schritte auf allen ISE-Softwareversionen für 2.x verwenden.

Hintergrundinformationen

Um die API nutzen zu können, muss in der ISE eine Authentifizierung für externe RESTful Services (ERS) aktiviert und Sponsor eingerichtet werden. ERS unterstützt die grundlegende Authentifizierung und wird über Port 9060 ausgeführt. Die Authentifizierungsdaten werden verschlüsselt und gehören zum Anforderungsheader. ERS fordert den ISE-Administrator auf, einem Benutzer spezielle Berechtigungen für die Durchführung von Vorgängen zuzuweisen.

In diesem Dokument werden die folgenden Konfigurationsschritte beschrieben:

1. Aktivierung von ERS auf der ISE

2. Admin- und Sponsorkonto für ERS einrichten

3. Gastkonto erstellen

4. Lesen, Aktualisieren, Löschen von Gastdaten

Konfigurieren

Aktivierung von ERS auf der ISE

Um die REST-API-Funktion auf der ISE nutzen zu können, muss ERS aktiviert werden.

Navigieren Sie zu Administration > System > Settings > ERS settings > Enable ERS for read/write as in image.

Alle Informationen zu ERS sind als Software Development Kit (SDK) für HTTPS-Port 9060 der ISE verfügbar. Der Zugriff erfolgt nach Aktivierung des ERS und Anmeldung bei einem Administratorkonto mit den Berechtigungen "ERS-Admin" oder "ERS-Operator".

Admin- und Sponsorkonto für ERS einrichten

Um ERS verwenden zu können, benötigt die ISE ein Administratorkonto, dem die Berechtigungen ERS-Admin oder ERS-Operator zugewiesen sind. Admin-Konten müssen erstellt und den entsprechenden Gruppen hinzugefügt werden. Alternativ kann der ERS-Zugang auch für das Super-Admin-Konto genutzt werden.

Um APIs für Gastfunktionen zu verwenden, benötigt ERS Admin rohe Daten der Portale wie die Portal-ID, Gruppen für Gastidentitäten usw. Um jedoch Gastdaten zu lesen/erstellen/aktualisieren oder zu löschen, ist ein Sponsorkonto mit aktiviertem ERS-Zugriff erforderlich.

• Für die Zwecke dieses Dokuments wird ein internes ISE-Benutzerkonto als Sponsor verwendet.
• Navigieren Sie zu Administration > Identity Management > Identities und fügen Sie einen Netzwerkzugriffsbenutzer hinzu, wie im Bild gezeigt.

• Dieses Benutzerkonto muss einer der Sponsorgruppen hinzugefügt werden.
• Das Beispielkonto ist der Standardsponsorengruppe ALL_ACCOUNTS zugeordnet. 
• Um ERS Zugriff für diese gesponserte Gruppe zu gewähren, gehen Sie zu Work Centers > Guest Access > Portal & Components > Sponsor Groups und öffnen Sie die zugewiesene Sponsorengruppe.
• Aktivieren Sie die Option: Greifen Sie auf Cisco ISE-Gastkonten über die programmgesteuerte Schnittstelle (Guest REST API) zu, wie im Bild gezeigt.

Erstellen eines Gastkontos

Um ein Gastkonto über eine API zu erstellen, muss die API als Sponsor und über ein von ihr erkenntes Portal an die ISE aufgerufen werden.

Schritt 1: Um die Portal-IDs aller auf der ISE vorkonfigurierten Sponsorportale abzurufen, verwenden Sie jeden REST-Client mit den folgenden Informationen:

Methode	ERHALTEN
URL	https://<ISE-IP>:9060/ers/config/sponsorportal
Anmeldeinformationen	ERS-Administratorberechtigungen verwenden
Header	Inhaltstyp: Anwendung/xml Akzeptieren: Anwendung/xml

Erwartete Ausgabe:

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

Der Wert ist die Portal-ID des Sponsorportals, die zur Erstellung von Gastbenutzern verwendet werden soll. In diesem Beispiel lautet die ID "274a95f0-2e58-11e9-98fb-0050568775a3".

Schritt 2: Verwenden Sie diesen API-Aufruf, um ein Gastkonto zu erstellen. Der Wert von portalID ist der Wert, der aus Schritt 1 abgerufen wird.

Methode	POST
URL	https://<ISE-IP>:9060/ers/config/guestuser/
Anmeldeinformationen	Verwenden Sie die Anmeldeinformationen des Sponsor-Kontos.
Header	Inhaltstyp: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml Akzeptieren: application/vnd.com.cisco.ise.identity.guestuser.2.0+xml
Text	<?xml version="1.0" encoding="UTF-8"?> <ns2:guestuser xmlns:ns2="identity.ers.ise.cisco.com"> <customFields> </customFields> <guestAccessInfo> <fromDate>25.04.2020 18:55</fromDate> <Location>Delhi</location> <bisDate>28.04.2020 19:55</toDate> <gültigeTage>3</gültigeTage> </guestAccessInfo> <guestInfo> <firma>Cisco</company> <emailAddress>abcd@cisco.com</emailAddress> <firstName>John</firstName> <lastName>Doe</lastName> <notificationLanguage>English</notificationLanguage> <Kennwort>9618</Kennwort> <phoneNumber>9999998877</phoneNumber> <smsServiceProvider>Global Default</smsServiceProvider> <userName>johndoe</userName> </guestInfo> <guestType>Contractor (default)</guestType> <PersonBeingVisited>abcd3@cisco.com</personBeingVisited> <portalId>274a95f0-2e58-11e9-98fb-0050568775a3</portalId> <reasonForVisit>Visiting Bob from Accounting</reasonForVisit> </ns2:GuestUser>

Hinweis: Der hier abgebildete Textinhalt kann als Vorlage verwendet werden (auch in SDK verfügbar). Stellen Sie sicher, dass der Wert von fromDate, toDate den gültigen Tagen entspricht. Der Standort, der Gasttyp und andere Werte müssen in Bezug auf die verwendete ISE gültig sein, nur dann ist der Anruf erfolgreich.

Hinweis: Bei den Anmeldeinformationen, die Sie bei diesem Anruf verwenden, muss es sich um ein gültiges Sponsorkonto handeln, das einer Sponsorgruppe zugeordnet ist. Die Administratorberechtigungen für ERS funktionieren hier nicht. Weitere Informationen finden Sie im vorherigen Abschnitt dieses Leitfadens.

Erwartete Ausgabe:

Navigieren Sie zu ISE-GUI > Master GuestReport, um zu überprüfen, ob das Konto erstellt wurde:

Hinweis: Es gibt keine Option, eine benutzerdefinierte Kombination aus Benutzername und Kennwort pro Gastkonto in einem Sponsorportal anzugeben. Diese API-Methode kann zur Erfüllung dieser Anforderung verwendet werden.

Lesen, Aktualisieren, Löschen von Gastdaten

Hier sind einige Beispiele für API-Aufrufe, um verschiedene Aktionen für Gastdaten durchzuführen. Alle verfügbaren Optionen und deren Formate sind im SDK verfügbar.

• Details zum Gastbenutzerkonto nach Namen abrufen:

Methode	ERHALTEN
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Anmeldeinformationen	Verwenden Sie die Anmeldeinformationen des Sponsor-Kontos.
Header	Inhaltstyp: Anwendung/xml Akzeptieren: Anwendung/xml

Erwartete Ausgabe:

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>

• Kennwort eines Gastbenutzers zurücksetzen:

Dazu muss zunächst die Gast-ID aus dem Anruf abgerufen und anschließend in dieser API verwendet werden. Die Benutzer-ID in diesem Beispiel lautet "3b967932-86f8-11ea-aafe-72889dc971d1".

Methode	PUT
URL	https://<ISE-IP>:9060/ers/config/guestuser/resetpassword/{id}
Anmeldeinformationen	Verwenden Sie die Anmeldeinformationen des Sponsor-Kontos.
Header	Inhaltstyp: Anwendung/xml Akzeptieren: Anwendung/xml

Diese Methode ermöglicht keine Angabe des neuen Kennworts. Die ISE gibt die Ausgabe mit dem neuen automatisch generierten Kennwort zurück.

Erwartete Ausgabe:

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>

•  Löschen Sie ein Gastkonto nach Namen:

Methode	LÖSCHEN
URL	https://<ISE-IP>:9060/ers/config/guestuser/name/{name}
Anmeldeinformationen	Verwenden Sie die Anmeldeinformationen des Sponsor-Kontos.
Header	Inhaltstyp: Anwendung/xml Akzeptieren: Anwendung/xml

Erwartete Ausgabe:

Überprüfen

Für diese Konfiguration ist derzeit kein Überprüfungsverfahren verfügbar.

Fehlerbehebung

Dieser Abschnitt enthält Informationen, die Sie zur Fehlerbehebung bei Ihrer Konfiguration verwenden können.

Einige häufige Fehler und deren mögliche Ursachen:

• Die Erstellung eines Gastkontos schlägt fehl und es wird ein Fehler ausgegeben:

     401 Unauthorized

     <message type="ERROR" code="CRUD operation exception">
    <title>Sponsor does not have permission to access REST Apis</title>
     </message>

Beheben: Das bedeutet, dass das für das Gastkonto verwendete Sponsorkonto einer Sponsorengruppe zugeordnet ist, bei der der ERS-Zugriff nicht aktiviert ist. Bearbeiten Sie die entsprechende Sponsorengruppe, und aktivieren Sie mithilfe der Programmschnittstelle (Guest REST API) den Zugriff auf Cisco ISE-Gastkonten.

   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>

Beheben: Die in den Anruf eingegebene Portal-ID ist auf der ISE nicht vorhanden oder falsch. Rufen Sie im Sponsorportal die richtige Portal-ID des Portals ab.

• API-Antwortcodes und deren mögliche Bedeutung:

      200 (OK): Gibt an, dass die REST-API die gewünschte Aktion erfolgreich ausgeführt hat.

      201 (erstellt): Gibt an, dass eine Ressource innerhalb einer Auflistung erstellt wurde.

      204 (ohne Inhalt): Diese wird normalerweise als Antwort auf PUT-, POST- oder DELETE-Anfragen gesendet.

     400 (Bad Request): Generischer Fehlercode für Probleme wie fehlgeformte Anforderungssyntax, ungültige Parameter usw. Lesen Sie die Nachrichtendetails, wenn diese verfügbar sind, um die Ursache zu verstehen.

     401 (nicht autorisiert): Dies weist darauf hin, dass die Aktion mit falschen Anmeldeinformationen durchgeführt wurde, keine Anmeldeinformationen vorhanden sind oder das Konto nicht berechtigt ist, diese Aktion auszuführen.

     500 (Interner Serverfehler): Zeigt ein Problem auf Serverseite an. Logs auf der ISE können dabei helfen, die Ursache zu verstehen.

Weitere Informationen zur Verwendung der REST-API für die ISE finden Sie unter Guest REST API.