Navigation durch API-Explorer der Secure Firewall demonstrieren

Einleitung

In diesem Dokument wird die Navigation durch den API-Explorer (Application Programming Interface) von Cisco FMC und Cisco FDM beschrieben.

Voraussetzungen

Grundlegendes Verständnis der REST-API.

Anforderungen

Für diese Demonstration ist der Zugriff auf die Benutzeroberfläche des Firepower Management Center (FMC) mit mindestens einem von diesem Firepower Management Center (FMC) verwalteten Gerät erforderlich. Für den FDM-Teil dieser Demonstration ist eine lokale Verwaltung einer FirePOWER Threat Defense (FTD) erforderlich, um Zugriff auf die FDM-GUI zu erhalten.

Verwendete Komponenten

• FMC V
• FTDv
• FTDv Lokal verwaltet

Die Informationen in diesem Dokument beziehen sich auf Geräte in einer speziell eingerichteten Testumgebung. Alle Geräte, die in diesem Dokument benutzt wurden, begannen mit einer gelöschten (Nichterfüllungs) Konfiguration. Wenn Ihr Netzwerk in Betrieb ist, stellen Sie sicher, dass Sie die möglichen Auswirkungen aller Befehle kennen.

Navigation durch FMC API-Explorer überprüfen

Um auf den FMC API Explorer zuzugreifen, navigieren Sie zur nächsten URL:

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

Sie müssen sich mit denselben Anmeldeinformationen anmelden, die auch für die FMC-GUI verwendet werden. Diese Anmeldeinformationen werden in einem Fenster eingegeben, das dem nächsten ähnelt, wenn Sie die API-Explorer-URLs eingeben.

Nach der Anmeldung wird deutlich, dass die API-Abfragen nach Kategorien unterteilt sind, die den möglichen Aufrufen entsprechen, die Sie mithilfe von APIs durchführen können.

Wenn Sie auf eine Kategorie klicken, wird sie erweitert und zeigt Ihnen die verschiedenen Anrufe an, die für diese Kategorie verfügbar sind. Diese Aufrufe werden zusammen mit den jeweiligen REST-Methoden und dem URI (Universal Resource Identifier) dieses Aufrufs angezeigt.

Im nächsten Beispiel fordern Sie an, die im FMC konfigurierten Zugriffsrichtlinien anzuzeigen. Klicken Sie auf die entsprechende Methode, um sie zu erweitern, und klicken Sie dann auf die Schaltfläche "Try it out".

Hervorzuheben ist, dass Sie Ihre Abfragen mit den verfügbaren Parametern in jedem API-Aufruf parametrisieren können. Nur solche mit roten Sternchen sind obligatorisch, die anderen können leer gelassen werden.

Die domainUUID ist beispielsweise für alle API-Aufrufe obligatorisch, wird jedoch im API-Explorer automatisch ausgefüllt.

Als Nächstes klicken Sie auf Ausführen, um diesen Anruf zu tätigen.

Bevor Sie auf "Ausführen" klicken, werden Ihnen Beispiele von Antworten auf die Anrufe angezeigt, um einen Eindruck davon zu erhalten, welche Antworten Sie erhalten können, je nachdem, ob die Anfrage richtig ist oder nicht.

Nachdem der API-Aufruf ausgeführt wurde, erhalten Sie zusammen mit der Antwortnutzlast den Antwortcode. In diesem Fall 200, was einer OK-Anfrage entspricht. Sie erhalten auch die cURL und die URL des Anrufs, den Sie gerade getätigt haben. Diese Informationen sind nützlich, wenn Sie diesen Anruf mit einem externen Client/einer externen Software tätigen möchten.

Die erhaltene Antwort gibt die im FMC konfigurierten ACPs zusammen mit ihrer Objekt-ID zurück. In diesem Fall werden diese Informationen im roten Feld im nächsten Bild angezeigt:

Diese objectID ist der Wert, den Sie in Aufrufen eingeben, die einen Verweis auf diesen ACP erfordern. Zum Beispiel, um eine Regel innerhalb dieses ACP zu erstellen.

Die URIs, die Werte zwischen geschweiften Klammern enthalten {}, sind Werte, die für diesen Aufruf erforderlich sind.  Denken Sie daran, dass domainUUID der einzige Wert ist, der automatisch gefüllt wird.

Die für diese Aufrufe erforderlichen Werte sind in der Aufrufbeschreibung angegeben. Um Regeln für einen ACP zu erstellen, benötigen Sie die policy-ID, wie im nächsten Bild zu sehen ist:

Diese policyID wird in das als containerUUID angegebene Feld eingegeben. Ein weiteres erforderliches Feld für POST-Methoden ist der Payload- oder Anforderungstext. Anhand der Beispiele können Sie Ihre Anforderungen anpassen.

Beispiel für eine geänderte Nutzlast:

{ "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" ] }

Wenn Sie den vorherigen Aufruf ausführen, erhalten Sie einen Antwortcode 201, der angibt, dass die Anforderung erfolgreich war und zur Erstellung der Ressource geführt hat.

Schließlich müssen Sie eine Bereitstellung vornehmen, damit diese Änderungen in der FTD wirksam werden, deren ACP geändert wurde.

Dazu müssen Sie eine Liste der Geräte abrufen, für die Änderungen bereitgestellt werden können.

Das Beispiel enthält ein Gerätepaar, das in Hochverfügbarkeit konfiguriert ist. Sie müssen die ID dieser HA erhalten. Wenn Sie ein eigenständiges Gerät sind, müssen Sie die ID dieses Geräts erhalten.

Die Abfrage, die zum Abrufen der Geräte-ID der HA erforderlich ist, lautet wie folgt:

Mit der Geräte-ID und der Bereitstellungsversionsnummer können Sie die Nutzlast des nächsten Anrufbeispiels ändern, um den Anruf für diese Bereitstellung zu tätigen.

Sobald dieser Aufruf ausgeführt wird, wenn alles korrekt ist, erhalten Sie eine Antwort mit Code 202.

Navigation in FDM API Explorer überprüfen

Um auf den FDM API Explorer zuzugreifen, können Sie eine Schaltfläche auf der FDM-GUI verwenden, um direkt darauf zuzugreifen, wie im folgenden Bild gezeigt:

Sobald Sie den API Explorer aufgerufen haben, werden die Abfragen auch in Kategorien unterteilt.

Um eine Kategorie zu erweitern, müssen Sie auf sie klicken. Anschließend können Sie jede der Operationen durch Klicken auf eine der Kategorien erweitern. Das erste, was in jeder Operation gefunden wird, ist ein Beispiel für eine OK-Antwort für diesen Anruf.

Als Nächstes sehen Sie die verfügbaren Parameter, mit denen Sie die Antworten auf Ihren Anruf beschränken können. Denken Sie daran, dass nur die als erforderlich markierten Felder für einen solchen Anruf erforderlich sind.

Schließlich finden Sie die möglichen Antwortcodes, die dieser Anruf zurückgeben kann.

Wenn Sie diesen Anruf tätigen möchten, klicken Sie auf Try It Out. Um diese Schaltfläche zu finden, müssen Sie nach unten blättern, bis Sie diese Schaltfläche finden, da sie sich am unteren Ende jedes Anrufs befindet.

Wenn Sie auf die Schaltfläche "Try It Out" klicken und es sich um einen Anruf handelt, für den keine weiteren Felder erforderlich sind, wird der Anruf sofort ausgeführt, und Sie erhalten eine Antwort.

Fehlerbehebung

Jeder Anruf generiert einen HTTP-Antwortcode und einen Antworttext. So können Sie leichter erkennen, wo der Fehler liegt.

Der nächste Fehler tritt häufig auf, wenn die Sitzung abgelaufen ist. Er weist darauf hin, dass das Token ungültig ist, da es abgelaufen ist.

Im Folgenden finden Sie Beispiele für HTTP-Antwortcodes, die Aufrufe zurückgeben können:

• Serie 2xx: Erfolg Es gibt mehrere Statuscodes: 200 (GET und PUT), 201 (POST), 202, 204 (DELETE). Sie zeigen einen erfolgreichen API-Aufruf an.
• 30x-Serie: Umleitung. Kann verwendet werden, wenn ein Client ursprünglich HTTP verwendet hat und zu HTTPS umgeleitet wurde.
• 4xx-Serie: Client-seitiger Fehler im API-Aufruf, der vom Client an den Server gesendet wurde. Zwei Beispiele umfassen einen 401-Statuscode, der angibt, dass die Sitzung nicht authentifiziert ist, und einen 403-Code, der einen unzulässigen Zugriffsversuch anzeigt.
• 5xx-Serie: Server-, Geräte- oder serviceseitiger Fehler. Dies kann daran liegen, dass der Geräte-API-Dienst deaktiviert wurde oder über das IP-Netzwerk nicht darauf zugegriffen werden kann.