Demostrar la navegación a través del Explorador de API de Secure Firewall

Introducción

Este documento describe la navegación a través del explorador de la interfaz de programación de aplicaciones (API) de Cisco FMC y Cisco FDM.

Prerequisites

Comprensión básica de la API REST.

Requirements

Es necesario que esta demostración tenga acceso a la GUI de Firepower Management Center (FMC) con al menos un dispositivo administrado por este Firepower Management Center (FMC). Para la parte de FDM de esta demostración, es necesario disponer de un Firepower Threat Defence (FTD) gestionado localmente para tener acceso a la GUI de FDM.

Componentes Utilizados

• FMCv
• FTDv
• FTDv gestionado localmente

La información que contiene este documento se creó a partir de los dispositivos en un ambiente de laboratorio específico. Todos los dispositivos que se utilizan en este documento se pusieron en funcionamiento con una configuración verificada (predeterminada). Si tiene una red en vivo, asegúrese de entender el posible impacto de cualquier comando.

Revisar la navegación a través del Explorador API FMC

Para acceder al explorador de API de FMC, vaya a la siguiente URL:

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

Debe iniciar sesión con las mismas credenciales utilizadas para la GUI de FMC. Estas credenciales se introducen en una ventana similar a la siguiente en la que se introducen las URL del explorador de API.

Una vez iniciada la sesión, se observa que las consultas de API se dividen por categorías correspondientes a las posibles llamadas que puede realizar mediante las API.

Al hacer clic en una categoría, se expande y muestra las diferentes llamadas disponibles para esta categoría. Estas llamadas se muestran junto con sus respectivos métodos REST y el identificador de recursos universal (URI) de esa llamada.

En el siguiente ejemplo, se realiza una solicitud para ver las políticas de acceso configuradas en el FMC. Haga clic en el método correspondiente para expandirlo y, a continuación, haga clic en el botón Try it out.

Algo a destacar es que puede parametrizar sus consultas con los parámetros disponibles en cada llamada API. Solo son obligatorios aquellos con asteriscos rojos, los demás pueden dejarse vacíos.

Por ejemplo, domainUUID es obligatorio para todas las llamadas API, pero en el Explorador de API esto se completa automáticamente.

El siguiente paso es hacer clic en Ejecutar para realizar esta llamada.

Antes de hacer clic en Ejecutar, puede ver ejemplos de respuestas a las llamadas para hacerse una idea de las posibles respuestas que puede obtener en función de si la solicitud es correcta o no.

Una vez que se ejecuta la llamada API, se obtiene, junto con la carga útil de respuesta, el código de respuesta. En este caso 200, que corresponde a una solicitud OK. También obtendrá la cURL y la URL de la llamada que acaba de realizar. Esta información es útil si desea realizar esta llamada con un cliente/software externo.

La respuesta obtenida devuelve los ACP configurados en el FMC junto con su objectID. En este caso, puede ver esta información en el cuadro rojo de la siguiente imagen:

Este objectID es el valor que se introduce en las llamadas que requieren referencia a este ACP. Por ejemplo, para crear una regla dentro de este ACP.

Los URI que contienen valores entre corchetes {0} son valores necesarios para realizar esta llamada.  Recuerde que domainUUID es el único valor que se completa automáticamente.

Los valores necesarios para estas llamadas se especifican en la descripción de la llamada. Para crear reglas para un ACP, necesita policyID, como puede ver en la siguiente imagen:

Este policyID se introduce en el campo especificado como containerUUID; otro campo obligatorio para los métodos POST es la carga útil o el cuerpo de la solicitud. Puede utilizar los ejemplos proporcionados para modificarlos según sus necesidades.

Ejemplo de carga útil modificada:

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

Una vez ejecutada la llamada anterior, se obtiene un código de respuesta 201, que indica que la solicitud se ha realizado correctamente y que ha dado lugar a la creación del recurso.

Por último, debe realizar un despliegue para que estos cambios surtan efecto en el FTD cuyo ACP se ha modificado.

Para esto, debe obtener la lista de dispositivos que tienen cambios listos para ser implementados.

El ejemplo contiene un par de dispositivos configurados en Alta disponibilidad. Debe obtener la ID de este HA; en caso de ser un dispositivo independiente, debe obtener la ID de ese dispositivo.

La consulta necesaria para obtener el ID de dispositivo del HA es la siguiente:

Con el ID de dispositivo y el número de versión de implementación, puede modificar la carga útil del siguiente ejemplo de llamada para realizar la llamada para realizar esta implementación.

Una vez ejecutada esta llamada, si todo es correcto, obtendrá una respuesta con el código 202.

Revisar la navegación mediante el Explorador de API de FDM

Para acceder al Explorador de la API de FDM, es posible utilizar un botón de la GUI de FDM para ir directamente a ella, como se muestra en la siguiente imagen:

Una vez en el Explorador de API, observará que las consultas también se dividen en categorías.

Para expandir una categoría, debe hacer clic en ella y, a continuación, puede expandir cada una de las operaciones haciendo clic en cualquiera de ellas. Lo primero que se encuentra dentro de cada operación es un ejemplo de una respuesta OK para esta llamada.

Lo siguiente que verá son los parámetros disponibles para restringir las respuestas de la llamada que realice. Recuerde que solo los campos marcados como obligatorios son obligatorios para realizar dicha llamada.

Por último, encontrará los posibles códigos de respuesta que puede devolver esta llamada.

Si desea realizar esta llamada, debe hacer clic en Try It Out. Para encontrar este botón, debe desplazarse hacia abajo hasta que encuentre este botón, ya que se encuentra en la parte inferior de cada llamada.

Al hacer clic en el botón Try It Out, si se trata de una llamada que no requiere más campos, se ejecuta inmediatamente y proporciona la respuesta.

Troubleshoot

Cada llamada genera un código de respuesta HTTP y un cuerpo de respuesta. Esto le ayuda a identificar dónde está el error.

El siguiente es un error común que ocurre cuando la sesión ha caducado, indicando que el token no es válido porque ha caducado.

A continuación, se muestran ejemplos de códigos de respuesta HTTP que las llamadas pueden devolver:

• 2xx Series: Éxito. Hay varios códigos de estado: 200 (GET y PUT), 201 (POST), 202, 204 (DELETE). Indican una llamada API correcta.
• Serie 30x: redirección. Se puede utilizar cuando un cliente utilizó originalmente HTTP y fue redirigido a HTTPS.
• 4xx Series: error en el lado del cliente en la llamada API que se envió desde el cliente al servidor. Dos ejemplos incluyen un código de estado 401, que indica que la sesión no está autenticada, y un código 403, que indica un intento de acceso prohibido.
• 5xx Series: fallo de servidor, dispositivo o servicio. Esto podría deberse a que el servicio API del dispositivo se ha deshabilitado o es inaccesible a través de la red IP