What You’ll Learn
- How to get started with the Cisco Secure Firewall Management Center (FMC) Representational State Transfer (REST) application programming interface (API)
- How to authenticate to the FMC REST API using the Python Requests library
- How to retrieve authentication and refresh tokens
- How to refresh time-limited tokens
What You’ll Need
- Access to FMC running version 7.0+
- A browser such as Chrome or Firefox to access the FMC GUI
- Python 3.6+ (with the Requests library installed)
With token-based authentication, you obtain a token by providing your username and password. You use the token to access an HTTP service for a limited time as opposed to providing your username and password. The access token can be used to access resources for up to 30 minutes, and it can be refreshed up to three times. It can take up to 90 minutes before you have to request a new token by providing your username and password.
The following diagram illustrates the concept of token-based authentication:
The FMC REST API is enabled by default. If you intend to use the REST API, you should confirm that it is enabled by checking the System/Configuration settings, as shown here:
It is also good practice to create a separate user account for carrying out REST API administrative tasks. In a shared sandbox environment, it is likely that these options are not visible or configurable!
The API Explorer provides a limited interface for the FMC REST API as well as a view of its capabilities. The API Explorer resides on the FMC and can be accessed via the FMC at https://<FMC_FQDN>/api/api-explorer. If you are currently using the Cisco DevNet FMC Sandbox, you can access the API Explorer here.
The API Explorer specifies the endpoints and methods supported in the FMC API. The focus of this tutorial is token-based authentication, which can be explored by clicking the REST API Quick Start Guide link located near the top of the API Explorer, as shown here:
When you click the Quick Start Guide link, you may be presented with several different versions of the guide. Select the guide that most closely matches the FMC version you are using.
Select Connecting with a Client in the Quick Start Guide, and scroll down to the Requesting an Authentication Token section. Make a note of the authentication request URL, which you will need when submitting a request for your authentication and refresh tokens.
In this topic, we are going to submit a token request to the FMC REST API. Log in to the Python REPL (Read-Eval-Print Loop), and import the Requests library. (Instructions for installing the library can be found here.)
import requests
In order to request an FMC access token, you will need administrator credentials as well as the fully qualified domain name (FQDN) of the FMC.
The following example includes the hostname of the FMC used in the Cisco DevNet FMC REST API Sandbox as well as sample values for the username and password. When testing these commands on your system, make sure that the values match your environment.
host = 'fmcrestapisandbox.cisco.com'
username = 'api_user'
password = 'api_user_password'
Create a variable for the authentication endpoint. Also, create a variable for the URL, whose value combines the host and auth_ep variables.
auth_ep = '/api/fmc_platform/v1/auth/generatetoken'
url = 'https://' + host + auth_ep
With basic authentication, a username and password are used in an authentication request. Typically, this is achieved using the HTTPBasicAuth class provided by the Requests library. The library also provides a simpler way of doing this by allowing you to pass a tuple containing your username and password into the auth = parameter.
auth = (username, password)
Like many RESTful APIs, the FMC REST API supports the JSON data interchange format. When consuming the API, it is important to specify that you are submitting JSON-formatted data using the headers parameter.
headers = {'content-type': 'application/json'}
The Requests library has a built-in warning function that can be used to suppress warnings. In addition, it is possible to disable Secure Sockets Layer (SSL) certificate verification using the verify parameter. The parameter is set to True by default, but setting it to False will disable verification warning messages. It is inadvisable to suppress these messages in a production environment.
Submit a token request by including the POST method as well as the auth, header, and verify parameters.
requests.packages.urllib3.disable_warnings()
response = requests.post(url, headers=headers, auth=auth, verify=False)
Check the response code and confirm that the response body is empty. Confirm that the authentication request is Base64 encoded. Retrieve the authentication and refresh tokens and assign them to variables.
response.status_code
response.content
response.request.headers['authorization']
access_token = response.headers['x-auth-access-token']
refresh_token = response.headers['x-auth-refresh-token']
In this topic, we are going to consume an endpoint using token-based authentication. Log in to the API Explorer, expand the System Information section, and look up the domain endpoint.
Assign the endpoint to a variable, and update the URL.
domain_ep = '/api/fmc_platform/v1/info/domain'
url = 'https://' + host + domain_ep
Update the headers to include the access token; the refresh token is optional.
headers = {'content-type': 'application/json', 'x-auth-access-token': access_token}
Submit a token-based authentication request, and retrieve the domain universally unique identifier (UUID). There is no need to include the user credentials.
response = requests.get(url, headers=headers, verify=False)
domain = response.json()['items'][0]['uuid']
Look up the hosts endpoint in the Object section of the API Explorer.
Assign the endpoint to a variable, and replace {domainUUID} with the value that you just retrieved. Submit a request, and extract the first host that you retrieve.
hosts_ep = '/api/fmc_config/v1/domain/' + domain + '/object/hosts'
url = 'https://' + host + hosts_ep
response = requests.get(url, headers=headers, verify=False)
first_host = response.json()['items'][0]
print(first_host)
In this final topic, we are going to refresh the token. Return to the REST API Quick Start Guide, and look up the endpoint for refreshing a token.
Assign the endpoint to a variable. Make sure that you include both the access and refresh tokens in the headers; the user credentials are not required. Submit a token refresh request, and verify that the tokens have changed.
host = 'fmcrestapisandbox.cisco.com'
username = 'api_user'
password = 'api_user_password'
print('The current access token is: ' + access_token)
refresh_ep = '/api/fmc_platform/v1/auth/refreshtoken'
url = 'https://' + host + refresh_ep
headers = {'content-type': 'application/json', 'x-auth-access-token': access_token, 'x-auth-refresh-token': refresh_token}
response = requests.post(url, headers=headers, verify=False)
new_access_token = response.headers['x-auth-access-token']
print('The new access token is: ' + new_access_token)
You can submit endpoint requests using your new token. (The original token is no longer valid.) A maximum of three token refreshes is permitted. The maximum lifetime for each token is 30 minutes.
The entire script is here for your reference. (Because this script was written with the interactive Python interpreter >>>, variable names will overlap.)
import requests
auth_ep = '/api/fmc_platform/v1/auth/generatetoken'
url = 'https://' + host + auth_ep
auth = (username, password)
headers = {'content-type': 'application/json'}
requests.packages.urllib3.disable_warnings()
response = requests.post(url, headers=headers, auth=auth, verify=False)
response.status_code
response.content
response.request.headers['authorization']
access_token = response.headers['x-auth-access-token']
refresh_token = response.headers['x-auth-refresh-token']
domain_ep = '/api/fmc_platform/v1/info/domain'
url = 'https://' + host + domain_ep
headers = {'content-type': 'application/json', 'x-auth-access-token': access_token}
response = requests.get(url, headers=headers, verify=False)
domain = response.json()['items'][0]['uuid']
hosts_ep = '/api/fmc_config/v1/domain/' + domain + '/object/hosts'
url = 'https://' + host + hosts_ep
response = requests.get(url, headers=headers, verify=False)
first_host = response.json()['items'][0]
print(first_host)
print('The current access token is: ' + access_token)
refresh_ep = '/api/fmc_platform/v1/auth/refreshtoken'
url = 'https://' + host + refresh_ep
headers = {'content-type': 'application/json', 'x-auth-access-token': access_token, 'x-auth-refresh-token': refresh_token}
response = requests.post(url, headers=headers, verify=False)
new_access_token = response.headers['x-auth-access-token']
print('The new access token is: ' + new_access_token)
You have completed this tutorial on Cisco Secure Firewall Management Center REST API Token Authentication. You have learned how to request an access token and refresh token using basic authentication. You have also learned how to use tokens for consuming FMC REST API endpoints and how to refresh tokens when they expire.