ISE-Guest accounts met REST API configureren

Inleiding

In dit document wordt beschreven hoe de optie Representational State Transfer (REST) API kan worden gebruikt voor het uitvoeren van taken die te maken hebben met gasten in de Identity Services Engine (ISE). Cisco Guest API is een op REST gebaseerde reeks bewerkingen die beveiligde HTTPS en geauthentiseerde toegang bieden om Cisco-gastgebruikers te beheren. Met API, kan men voor gastgebruikers creëren, lezen, bijwerken, wissen en zoeken.

Voorwaarden

Vereisten

Cisco raadt u aan om de kennis van deze onderwerpen te hebben:

• ISE
• Externe REST-services
• REST-klanten zoals slapeloosheid, RESTED, enz.

Gebruikte componenten

De informatie in dit document is gebaseerd op de volgende software- en hardware-versies:

• Cisco ISE, release 2.6
• Insomnia REST client v7.1.1

De informatie in dit document is gebaseerd op de apparaten in een specifieke laboratoriumomgeving. Alle apparaten die in dit document worden beschreven, hadden een opgeschoonde (standaard)configuratie. Als uw netwerk levend is, zorg er dan voor dat u de mogelijke impact van om het even welke opdracht begrijpt.

Opmerking: De procedure is vergelijkbaar of identiek voor andere ISE-versies. U kunt deze stappen op alle 2.x ISE-softwarereleases gebruiken, tenzij anders aangegeven.

Achtergrondinformatie

Om gebruik te maken van de API, moet in ISE externe RESTful Services (ERS) worden opgezet en de authenticatie van sponsors worden gesponsord. ERS ondersteunt basisauthenticatie en wordt uitgevoerd in haven 9060. De authenticiteitsreferenties worden versleuteld en maken deel uit van de header van het verzoek. ERS vereist dat de ISE-beheerder speciale rechten aan een gebruiker toewijst om bewerkingen uit te voeren.

Het document bevat deze configuratiestappen:

1. Inschakelen op ISE

2. Beheersbeheer en sponsorrekening voor ERS instellen

3. Maak een gastaccount

4. Lees, update, verwijder gastgegevens

Configureren

ERS op ISE inschakelen

Om de REST API-functie op ISE te kunnen gebruiken, moet ERS zijn ingeschakeld.

Navigeer naar Beheer > Systeem > Instellingen > ERS instellingen > ERS inschakelen voor lezen/schrijven zoals in de afbeelding.

Alle informatie met betrekking tot ERS is beschikbaar als een softwareontwikkelingskit (SDK) op HTTPS-poort 9060 van ISE. Dit is toegankelijk nadat u ERS en loggen in met een beheeraccount met de rechten van "ERS-Admin" of "ERS-Exploitant" hebt ingeschakeld.

Admin- en sponsoraccount voor ERS instellen

Om ERS te kunnen gebruiken, vereist ISE een administratieve rekening die de bevoegdheden van ERS-Admin of ERS-operator heeft. Er moeten Admin-accounts worden aangemaakt en toegevoegd aan de respectievelijke groepen. In plaats hiervan werkt ERS-toegang ook voor de Super-Admin-account.

Om API’s te kunnen gebruiken voor gastfuncties, heeft ERS-beheerder ruwe gegevens nodig van portals zoals de portal-ID, groepen met gastidentiteit, enz. Echter, om eventuele gastgegevens te kunnen lezen/maken/bijwerken of verwijderen, is een sponsoraccount met toegang tot ERS vereist.

• Voor de toepassing van dit document wordt een interne ISE-gebruikersrekening als sponsor gebruikt.
• Navigeer naar Beheer > Identity Management > Identificaties en voeg een gebruiker van de netwerktoegang toe zoals in de afbeelding.

• Deze gebruikersaccount moet aan een van de sponsorgroepen worden toegevoegd.
• De voorbeeldaccount is toegewezen aan de standaard sponsor groep ALL_ACCOUNTS. 
• Om ERS toegang te geven tot deze gesponsorde groep, gaat u naar Workcenters > Guest Access > Portal & Componenten > Sponsordroepen en opent u de toegewezen sponsor groep.
• Schakel de optie in: Toegang tot Cisco ISE-gastrekeningen met het gebruik van de programmeerinterface (Guest REST API) zoals in de afbeelding getoond.

Een afbeeldingsaccount maken

Om een gastaccount via API te maken, is het noodzakelijk dat de API-oproep wordt gericht aan ISE als sponsor en via een gesponsord portaal dat het erkent.

Stap 1. Om de portal-ID’s van alle sponsor portals die vooraf op ISE zijn geconfigureerd te verkrijgen, gebruikt u elke REST-client met de hier verstrekte informatie:

Methode	KRIJGEN
URL	https://<ISE-IP>:9060/ers/configuratie/sponsorportal
Credentials	Gebruik ERS-admins
Koppen	Content-Type: toepassing/xml Aanvaard: toepassing/xml

Verwacht resultaat:

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

De waarde van interesse is de Portal ID van het Sponsor-portal dat bedoeld is om gastgebruikers te creëren. De ID is "274a95f0-2e58-11e9-98fb-0050568775a3" in dit voorbeeld.

Stap 2. Gebruik deze API-oproep om een gastaccount aan te maken. De waarde van portalID hier is die van Stap 1.

Methode	POST
URL	https://<ISE-IP>:9060/ers/configuratie/guestuser/
Credentials	Accountreferenties sponsoren
Koppen	Content-Type: application/vnd.com.cisco.ise.Identity.guestuser.2.0+xml Aanvaard: application/vnd.com.cisco.ise.Identity.guestuser.2.0+xml
Tekst	<?xml versie="1.0" codering="UTF-8"> <ns2:guestuser xmlns:ns2="identiteit.ers.ise.cisco.com"> <maatvelden> </op maat gemaakte velden> <gasttoegang>Info> <vanafDatum>25-04-2020 18:55</vanafDatum> <locatie>Delhi</locatie> <to-date>28-04-2020 19:55</to-date> <geldige dagen>3</geldige dagen> </gastAccessInfo> <gastinformatie> <bedrijf>Cisco</bedrijf> <e-mailadres>abcd@cisco.com</e-mailAddress> <voornaam>John</voornaam> <lastName>Doe</lastName> <noticeLanguage>Engels</notificationLanguage> <wachtwoord>9618</wachtwoord> <telefoonnummer>9999998877</telefoonnummer> <smsServiceProvider>Wereldwijde standaard</smsServiceProvider> <userName>code</userName> </gastinformatie> <gastopcontact>Contractor (standaard)</gastopcontact> <persoon wordtBezocht>abcd3@cisco.com</persoonBeingVisite> <portalID>274a95f0-2e58-11e9-98fb-005056875a3</portalID> <REDENEN VOOR BEZOEK>Bob van een account</REDENEN VOOR BEZOEK> </ns2:guestgebruiker>

Opmerking: De lichaamsinhoud die hier wordt getoond, kan als een sjabloon worden gebruikt (ook beschikbaar in SDK). Zorg ervoor dat de datum van datum tot datum overeenkomt met geldige dagen. De locatie, het type gast en andere waarden moeten geldig zijn in verhouding tot de gebruikte ISE, dan zal de oproep slagen.

Opmerking: De geloofsbrieven die bij deze oproep worden gebruikt moeten een geldige sponsor account zijn die in kaart is gebracht aan een sponsor groep. ERS-admin-referenties hier werken niet. Raadpleeg het vorige gedeelte van deze handleiding voor meer informatie.

Verwacht resultaat:

Navigeer naar ISE GUI > Master GuestReport om te controleren of de account is aangemaakt:

Opmerking: Er is geen optie om per gastaccount een aangepaste gebruikersnaam en wachtwoordcombinatie van een sponsorportal op te geven. Deze API-methode kan worden gebruikt om aan dat vereiste te voldoen.

Gegevens lezen, bijwerken, verwijderen

Hier zijn een paar voorbeelden API aanroepen om verschillende acties op gastgegevens uit te voeren. Alle beschikbare opties en hun bestandsindelingen zijn in SDK beschikbaar.

• Geef de gegevens van een gastgebruikersaccount op naam:

Methode	KRIJGEN
URL	https://<ISE-IP>:9060/ers/configuratie/guestuser/name/ {naam}
Credentials	Accountreferenties sponsoren
Koppen	Content-Type: toepassing/xml Aanvaard: toepassing/xml

Verwacht resultaat:

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>

• Reset een wachtwoord voor gastgebruiker:

Dit vereist om eerst de gast ID van de vraag te halen en dan het in deze API te gebruiken. De gebruiker-ID is "3b967932-86f8-11ea-aafe-72889dc971d1" in dit voorbeeld.

Methode	PUT
URL	https://<ISE-IP>:9060/ers/configuratie/guestuser/resetpassword/ {id}
Credentials	Accountreferenties sponsoren
Koppen	Content-Type: toepassing/xml Aanvaard: toepassing/xml

Met deze methode kan het nieuwe wachtwoord niet worden ingesteld. ISE zal de uitvoer teruggeven met het nieuwe wachtwoord dat automatisch wordt gegenereerd.

Verwachte productie:

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>

•  Verwijder een gastaccount op naam:

Methode	VERWIJDEREN
URL	https://<ISE-IP>:9060/ers/configuratie/guestuser/name/ {naam}
Credentials	Accountreferenties sponsoren
Koppen	Content-Type: toepassing/xml Aanvaard: toepassing/xml

Verwachte productie:

Verifiëren

Er is momenteel geen verificatieprocedure beschikbaar voor deze configuratie.

Problemen oplossen

Deze sectie verschaft informatie die u kunt gebruiken om problemen met uw configuratie op te lossen.

Sommige voorkomende fouten en de mogelijke oorzaken ervan:

• Bij het maken van een gastaccount is er een fout:

     401 Unauthorized

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

Afbeelding: Dit betekent dat de sponsorrekening die wordt gebruikt voor het maken van de gastrekening in kaart wordt gebracht aan een sponsor groep waar ERS geen toegang hebben. Bewerk de sponsor groep die aan dit correspondeert en laat de gastrekeningen van Cisco ISE van de Toegang met het gebruik van de programmeerinterface (Gast REST API) toe.

   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>

Afbeelding: De portal-ID die in de oproep is ingevoerd, bestaat niet op ISE of is onjuist. Ga van de oproep tot sponsorportal op de juiste portal ID van de portal.

• API-responscodes en de mogelijke betekenis ervan:

      200 (OK): Geeft aan dat REST API de gewenste bewerking heeft uitgevoerd.

      201 (Gemaakt): Duidt op een resource dat binnen een verzameling is gemaakt.

      204 (geen inhoud): Dit wordt meestal verstuurd als antwoord op PUT, POST of DELETE verzoeken.

     400 (slechte aanvraag): Generic error code voor problemen als de mislukte syntaxis van het verzoek, ongeldige parameters, enzovoort. Lees de eventuele berichtgegevens om de oorzaak te begrijpen.

     401 (niet-toegestaan): Dit geeft aan dat de actie is ondernomen met verkeerde geloofsbrieven, geen geloofsbrieven of de account is niet gemachtigd om deze actie uit te voeren.

     500 (interne serverfout): Geeft een probleem aan op de server. Logs op ISE kunnen helpen de oorzaak te begrijpen.

Raadpleeg voor meer informatie over REST API-gebruik voor ISE de Guest REST API.