Navigatie demonstreren via de API-Explorer van Secure Firewall

Inleiding

In dit document wordt de navigatie beschreven via de API-verkenner (Application Programming Interface) van Cisco FMC en Cisco FDM.

Voorwaarden

Basiskennis van REST API.

Vereisten

Deze demonstratie moet toegang hebben tot de gebruikersinterface van het Firepower Management Center (FMC) met ten minste één apparaat dat wordt beheerd door dit Firepower Management Center (FMC). Voor het FDM-deel van deze demonstratie is het nodig om een Firepower Threat Defense (FTD) lokaal te laten beheren om toegang te krijgen tot de FDM GUI.

Gebruikte componenten

• FMCv
• FTDv
• FTDv Lokaal beheerd

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 live is, moet u zorgen dat u de potentiële impact van elke opdracht begrijpt.

Navigatie bekijken via FMC API Explorer

Om toegang te krijgen tot de FMC API explorer, navigeert u naar de volgende URL:

https://<FMC_mgmt_IP>/api/api-explorer

U moet inloggen met dezelfde referenties als voor de FMC GUI. Deze referenties worden ingevoerd in een venster dat lijkt op het volgende wanneer u de API explorer URL's invoert.

Eenmaal ingelogd, wordt gezien dat de API-query's worden verdeeld door categorieën die overeenkomen met de mogelijke oproepen die u kunt maken met behulp van API's.

Opmerking: Niet alle configuratiefuncties die beschikbaar zijn via de GUI of CLI zijn beschikbaar via de API's.

Wanneer u op een rubriek klikt, wordt deze uitgebreid met de verschillende oproepen die beschikbaar zijn voor deze rubriek. Deze oproepen worden getoond samen met hun respectieve REST-methoden en de Universal Resource Identifier (URI) van die oproep.

In het volgende voorbeeld vraagt u om het toegangsbeleid te zien dat in de FMC is geconfigureerd. U klikt op de bijbehorende methode om deze uit te vouwen en klikt vervolgens op de knop Probeer het uit.

Iets om te benadrukken is dat u uw zoekopdrachten kunt parametriseren met de beschikbare parameters in elke API-oproep. Alleen degenen met rode sterretjes zijn verplicht, de anderen kunnen leeg worden gelaten.

Zo is de domeinUUID verplicht voor alle API-aanroepen, maar op de API Explorer vult dit automatisch in.

De volgende stap is om op Uitvoeren te klikken om deze oproep te doen.

Voordat u op Uitvoeren klikt, ziet u voorbeelden van reacties op de oproepen om een idee te krijgen van de mogelijke antwoorden die u kunt krijgen, afhankelijk van of het verzoek correct is of niet.

Zodra de API-oproep is uitgevoerd, verkrijgt u, samen met de responspayload, de responscode. In dit geval 200, wat overeenkomt met een OK-verzoek. U krijgt ook de cURL en de URL van het gesprek dat u zojuist hebt gemaakt. Deze informatie is handig als u dit gesprek wilt voeren met een externe client/software.

Het verkregen antwoord retourneert de ACP's die in de FMC zijn geconfigureerd samen met hun objectID. In dit geval kunt u deze informatie zien in het rode vak in de volgende afbeelding:

Deze objectID is de waarde die u invoert in oproepen die een verwijzing naar deze ACP vereisen. Bijvoorbeeld om binnen deze ACS een regeling te creëren.

{} De URI's die waarden bevatten tussen krullende haakjes zijn waarden die nodig zijn om deze oproep te doen.  Vergeet niet dat domeinUUID de enige waarde is die automatisch wordt ingevuld.

De vereiste waarden voor deze oproepen worden gespecificeerd in de beschrijving van de oproep. Om regels voor een ACP te maken, hebt u de policyID nodig, zoals u in de volgende afbeelding kunt zien:

Deze policyID wordt ingevoerd in het veld dat is opgegeven als containerUUID, een ander vereist veld voor POST-methoden is de payload of de aanvraaginstantie. U kunt de gegeven voorbeelden gebruiken om aan uw behoeften aan te passen.

Voorbeeld van gewijzigde payload:

{ "action": "ALLOW", "enabled": true, "type": "AccessRule", "name": "Testing API rule", "sendEventsToFMC": false, "logFiles": false, "logBegin": false, "logEnd": false, "sourceZones": { "objects": [ { "name": "Inside_Zone", "id": "8c1c58ec-8d40-11ed-b39b-f2bc2b448f0d", "type": "SecurityZone" } ] }, "destinationZones": { "objects": [ { "name": "Outside_Zone", "id": "c5e0a920-8d40-11ed-994a-900c72fc7112", "type": "SecurityZone" } ] }, "newComments": [ "comment1", "comment2" ] }

Opmerking: De beschikbare zones, samen met hun ID's, kunnen worden verkregen met behulp van de volgende query.

Nadat u de vorige oproep hebt uitgevoerd, krijgt u een 201-antwoordcode, die aangeeft dat de aanvraag is geslaagd en heeft geleid tot het maken van de bron.

Tot slot moet u ervoor zorgen dat deze veranderingen worden doorgevoerd in het FTD waarvan de ACS-overeenkomst is gewijzigd.

Hiervoor moet u de lijst met apparaten verkrijgen die wijzigingen hebben die klaar zijn om te worden geïmplementeerd.

Het voorbeeld bevat een paar apparaten die zijn geconfigureerd in High Availability. U moet de ID van deze HA verkrijgen, in het geval van een standalone apparaat, moet u de ID van dat apparaat verkrijgen.

De query die nodig is om de apparaat-ID van de HA te verkrijgen is als volgt:

Met de apparaat-ID en het versienummer van de implementatie kunt u de payload van het volgende voorbeeld van de oproep wijzigen om de oproep te doen om deze implementatie uit te voeren.

Zodra deze oproep is uitgevoerd, als alles correct is, krijgt u een antwoord met code 202.

Navigatie bekijken via FDM API Explorer

Om toegang te krijgen tot de FDM API Explorer, is het mogelijk om een knop op de FDM GUI te gebruiken om er rechtstreeks naar toe te gaan, zoals getoond in de volgende afbeelding:

Eenmaal in de API Explorer merkt u dat de query's ook zijn onderverdeeld in categorieën.

Om een categorie uit te vouwen, moet u erop klikken en vervolgens kunt u elk van de bewerkingen uitvouwen door op een van hen te klikken. Het eerste dat in elke bewerking wordt gevonden, is een voorbeeld van een OK-respons voor deze oproep.

Het volgende dat u ziet, zijn de beschikbare parameters om de antwoorden van de oproep die u doet te beperken. Vergeet niet dat alleen de velden die als verplicht zijn gemarkeerd verplicht zijn om een dergelijke oproep te doen.

Tot slot vindt u de mogelijke antwoordcodes die deze oproep kan retourneren.

Als u dit gesprek wilt voeren, moet u op Uitproberen klikken. Om deze knop te vinden, moet u naar beneden scrollen totdat u deze knop vindt, omdat deze zich onderaan elk gesprek bevindt.

Wanneer u op de knop Probeer het uit klikt, als het een oproep is waarvoor niet meer velden nodig zijn, wordt deze onmiddellijk uitgevoerd en krijgt u het antwoord.

Problemen oplossen

Elke oproep genereert een HTTP-responscode en antwoordinstantie. Dit helpt je om te bepalen waar de fout zit.

De volgende is een veelvoorkomende fout die optreedt wanneer de sessie is verlopen, wat aangeeft dat de token ongeldig is omdat deze is verlopen.

De volgende zijn voorbeelden van HTTP-antwoordcodes die oproepen kunnen retourneren:

• 2xx serie: Succes. Er zijn verschillende statuscodes: 200 (GET en PUT), 201 (POST), 202, 204 (DELETE). Ze wijzen op een succesvolle API-oproep.
• 30x reeks: Omleiding. Kan worden gebruikt wanneer een client oorspronkelijk HTTP gebruikte en werd omgeleid naar HTTPS.
• 4xx-reeks: fout aan de clientzijde in de API-aanroep die van de client naar de server is verzonden. Twee voorbeelden zijn een 401-statuscode, die aangeeft dat de sessie niet is geverifieerd, en een 403-code, die een verboden toegangspoging aangeeft.
• 5xx-reeks: storing van server, apparaat of service. Dit kan het gevolg zijn van het feit dat de API-service van het apparaat is uitgeschakeld of niet toegankelijk is via het IP-netwerk