What You’ll Learn

What You’ll Need

The FMC supports REST-based API calls to configure, monitor, or troubleshoot firewall devices operating on the network. When the administrator needs to manage only one device, APIs can have an enormous impact on the workload of managing a device. For example, what if the administrator needs to update the Application Visibility and Control (AVC) rules every day? This type of management can take a lot of time on the administrator’s end. Why not use APIs to make these rapid changes?

img.png

As you can see below, the Python client will be considered the REST Client, and the FMC server will be the REST API. The process starts by requesting an access token and a refresh token from the FMC server. This request will allow the user to send future API calls to the FMC. The access token is active for only 30 minutes, but it can be refreshed with the refresh token up to three times. After the token expires, it will need to be requested again from the FMC.

img.png

The FMC gives the user access to the API Explorer, which will allow the user to see which type of APIs can be made and how they should be formatted.

img.png

The API Explorer website can be accessed from the FMC using the /api/api-explorer URI. For example, if your FMC hostname is https://myfmc.test.com, then the site URL will be https://myfmc.test.com/api/api-exlorer.

Once you successfully log in, the API Explorer list of supported API objects will appear.

img.png

If you select an object, it will give you a list of API verbs (GET, PUT, POST, and DELETE) that you can execute using that object.

img.png

In this example, you can see that we selected the domain object, which will give the API user information about the domains that are configured on the FMC. Note the Try it out button.

img.png

This will give you the option to execute API calls on the API Explorer for testing. It will also give you example output as well as values that will be sent back from the FMC. The output of the API call will be in JSON encoding.

img.png

In order to make an API call to the FMC, you will need an access token. (The refresh token is optional.)

First, install the requests and HTTPBasicAuth libraries in Python, using pip install.

python3 -m pip install requests
python3 -m pip install http-basic-auth

After the pip install is done, you can now import the libraries into your Python script.

import requests
from requests.auth import HTTPBasicAuth

To request an access token from the FMC, you will need your administrator account information. You can then set the information as variables. The fully qualified domain name (FQDN) of the FMC must be included.

FMC_HOST = 'myfmc.domain.com'
USERNAME = 'admin'
PASSWORD = 'mypassword'

This action will be included as part of another variable that will use the HTTPBasicAuth library and will allow the request to be sent in the correct format.

basic = HTTPBasicAuth(USERNAME, PASSWORD)

The payload and the header variables will then need to be set. (The payload is required when you are sending data back to the FMC.)

payload={}

headers = {
'Content-Type': 'application/json'
}

Using the API Explorer, set the object URL as a variable. The f is used to format the URL; insert the FQDN using the {}.

url = f"https://{FMC_HOST}/api/fmc_platform/v1/auth/generatetoken"

Now, you will create the API request call, using the Python requests library. This is where the variables will be inserted as parameters (headers, data, auth). If the FMC is using a self-signed certificate, then the verify parameter will need to be set to False.

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

The last step is outputting the tokens. This if and else statement will output it from the response API. If it fails, it will also output the status code errors generated with text.

if response.status_code == 204:
    print()
    print("Token")
    print(response.headers["X-auth-access-token"])
    print()
    print("Refresh Token")
    print(response.headers["X-auth-refresh-token"])
    print()
    print("Domain UUID")
    print(response.headers["DOMAIN_UUID"])
    print()
else:
    print(f'Error: {response.status_code} - {response.text}’)

The final script should look like this:

import requests
from requests.auth import HTTPBasicAuth

FMC_HOST = ‘myfmc.domain.com'
USERNAME = 'admin'
PASSWORD = ‘mypassword'
basic = HTTPBasicAuth(USERNAME, PASSWORD)

payload={}

headers = {
'Content-Type': 'application/json'
}

url = f"https://{FMC_HOST}/api/fmc_platform/v1/auth/generatetoken"

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

if response.status_code == 204:
    print()
    print("Token")
    print(response.headers["X-auth-access-token"])
    print()
    print("Refresh Token")
    print(response.headers["X-auth-refresh-token"])
    print()
    print("Domain UUID")
    print(response.headers["DOMAIN_UUID"])
    print()
else:
    print(f'Error: {response.status_code} - {response.text}’)

If the request is successful, you will get the following output. Note that we also requested the domain universally unique identifier (UUID) information, which will be required when we make future API calls.

img.png

After the tokens have been generated, we can use them to make future API calls. But remember, the tokens will be active for only 30 minutes, unless you use the refresh token.

Which types of API calls can we make using the access token? That depends on what you want to do on the FMC. You can request output information on a configuration that is already on the FMC, or you can push a new configuration change to the FMC.

For example, what if you want to get a list of all the IP network objects that are configured on the FMC? First, you will need to get the correct URL from the API Explorer to make the API call, and then you will need to apply it to a Python script.

The URL for the IP network objects on the FMC is: https://{FMC_HOST}/api/fmc_config/v1/domain/{domain_UUID}/object/networks.

The URL includes the {FMC_HOST} and the {domain_UUID}; these will be set as variables. The domain UUID allows the administrator to break up the FMC into subconfigurations. This feature gives the administrators the option of assigning certain firewalls that are registered on the FMC to be administered by a specific administrator or user.

Here is the Python script using the IP network objects:

import requests
import json

FMC_HOST = 'myfmc.domain.com'
token = <token>
refresh_token = <r_token>

domain_UUID = 'e276abec-e0f2-11e3-8169-6d9ed49b625f'

payload={}

headers = {
'Content-Type': 'application/json',
'X-auth-access-token': f'{token}',
'X-auth-refresh-token': f'{refresh_token}'
}

url = f"https://{FMC_HOST}/api/fmc_config/v1/domain/{domain_UUID}/object/networks"

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

json_output = json.dumps(response.json(), indent=4)
print(json_output)

The script will output the information in JSON encoding:

img.png

As you can see, the script displays the currently configured IP network objects on the FMC.

Learn More