Erstellen eines Authentifizierungstokens für FMC-REST-API-Interaktionen

Einleitung

In diesem Dokument wird beschrieben, wie sich ein API-Administrator beim FirePOWER Management Center (FMC) authentifizieren, Token generieren und diese für weitere API-Interaktionen verwenden kann.

Voraussetzungen

Anforderungen

Cisco empfiehlt, dass Sie über Kenntnisse in folgenden Bereichen verfügen:

• FirePOWER Management Center (FMC) - Funktionen und Konfiguration (Konfigurationsanleitung)
• Verständnis der verschiedenen REST-API-Aufrufe (Was sind REST-APIs?)
• Lesen der FMC API Quick Start Guide.

Verwendete Komponenten

• Firepower Management Center, das REST-APIs (Version 6.1 oder höher) mit aktivierter REST-API unterstützt.
• REST-Clients wie Postman, Python-Skripte, CURL usw.

Hintergrundinformationen

REST-APIs werden aufgrund des einfachen programmierbaren Ansatzes, den Netzwerkmanager zur Konfiguration und Verwaltung ihrer Netzwerke verwenden können, immer beliebter. FMC unterstützt die Konfiguration und das Management über einen beliebigen REST-Client sowie den integrierten API-Explorer.

Konfigurieren

REST-API auf FMC aktivieren

Schritt 1: Navigieren Sie zu System>Konfiguration>REST API Preferences>Enable REST API.

Schritt 2: Aktivieren Sie das Kontrollkästchen REST API aktivieren.

Schritt 3. Klicken Sie auf Speichern, um das Dialogfeld Erfolgreiches Speichern anzuzeigen, wenn die REST-API aktiviert ist, wie in der Abbildung dargestellt:

Erstellen eines Benutzers auf dem FMC

Als Best Practice für die Verwendung der API-Infrastruktur auf FMC wird empfohlen, UI-Benutzer und Skript-Benutzer getrennt zu halten. Im Leitfaden zu Benutzerkonten für FMC finden Sie Informationen zu den verschiedenen Benutzerrollen und den Richtlinien zum Erstellen neuer Benutzer.

Schritte zum Anfordern eines Authentifizierungstokens

Schritt 1. Öffnen Sie den REST API Client.

Schritt 2: Legen Sie den POST-Befehl des Clients fest (URL: https://<management_center_IP_or_name>/api/fmc_platform/v1/auth/generatetoken.

Schritt 3: Integrieren Sie den Benutzernamen und das Kennwort als einfachen Authentifizierungs-Header. Der POST-Text sollte leer sein.

Beispiel für eine Authentifizierungsanforderung mit Python:

import requests
url = "https://10.10.10.1//api/fmc_platform/v1/auth/generatetoken"

payload = {}
headers = {
'Authorization': 'Basic Y2lzY291c2VyOmNpc2NwYXBpdXNlcg=='
}

response = requests.request("POST", url, headers=headers, data = payload, verify=False)
print(response.headers)

Ein weiteres Beispiel für eine Authentifizierungsanforderung mit CURL:

$ curl --request POST 'https://10.10.10.1/api/fmc_platform/v1/auth/generatetoken' --header 'Authorization: Basic Y2lzY291c2VyOmNpc2NwYXBpdXNlcg==' -k -i
HTTP/1.1 204 204
Date: Tue, 11 Aug 2020 02:54:06 GMT
Server: Apache
Strict-Transport-Security: max-age=31536000; includeSubDomains
Cache-Control: no-store
Accept-Ranges: bytes
Vary: Accept-Charset,Accept-Encoding,Accept-Language,Accept
X-auth-access-token: aa6f8326-0a0c-4f48-9d85-7a920c0fdca5
X-auth-refresh-token: 674e87d1-1572-4cd1-b86d-3abec04ca59d
USER_UUID: fc47b914-8121-11ea-ac18-f0428d0155cd
DOMAIN_ID: 111
DOMAIN_UUID: e276abec-e0f2-11e3-8169-6d9ed49b625f
global: e276abec-e0f2-11e3-8169-6d9ed49b625f
DOMAINS: [{"name":"Global","uuid":"e276abec-e0f2-11e3-8169-6d9ed49b625f"}]
X-Frame-Options: SAMEORIGIN
X-UA-Compatible: IE=edge
X-Permitted-Cross-Domain-Policies: none
X-XSS-Protection: 1; mode=block
Referrer-Policy: same-origin
Content-Security-Policy: base-uri 'self'
X-Content-Type-Options: nosniff

Beispiel von einem GUI-basierten Client wie Postman, wie im Bild gezeigt:

Nachfolgende API-Anforderungen werden gesendet

Anmerkung: In der Ausgabe sehen Sie die Response-Header und nicht den Response-Body. Der eigentliche Antworttext ist leer.  Die wichtigen Headerinformationen, die extrahiert werden müssen, sind X-auth-access-token, X-auth-refresh-token und DOMAIN_UUID.

Nachdem Sie sich erfolgreich bei FMC authentifiziert und die Token extrahiert haben, müssen Sie für weitere API-Anfragen die folgenden Informationen nutzen:

• Fügen Sie den Header X-auth-access-token <Wert des Authentifizierungstokens> als Teil der Anforderung hinzu.
• Fügen Sie die Header X-auth-access-token <Authentifizierungstokenwert> und X-auth-refresh-token <Aktualisierungstokenwert> in Anforderungen zum Aktualisieren des Tokens hinzu.
• Verwenden Sie die Domain_UUID aus dem Authentifizierungstoken in allen REST-Anforderungen an den Server.

Mit diesen Header-Informationen können Sie mithilfe von REST-APIs erfolgreich mit dem FMC interagieren.

Fehlerbehebung bei gängigen Problemen

• Der für die Authentifizierung gesendete Anforderungs- und Antworttext des POST ist leer. Sie müssen die grundlegenden Authentifizierungsparameter im Anforderungsheader übergeben. Alle Tokeninformationen werden über die Antwortheader zurückgegeben.

• Wenn Sie den REST-Client verwenden, werden möglicherweise Fehler im Zusammenhang mit dem SSL-Zertifikatproblem aufgrund eines selbstsignierten Zertifikats angezeigt. Sie können diese Validierung je nach verwendetem Client deaktivieren.

• Die Benutzeranmeldeinformationen können nicht gleichzeitig für die REST-API und die GUI-Schnittstellen verwendet werden, und der Benutzer wird ohne Warnung abgemeldet, wenn er für beide verwendet wird.

• Die Authentifizierungstoken der FMC REST API sind 30 Minuten lang gültig und können bis zu dreimal aktualisiert werden.