There are many authentication methods used by RESTful APIs, but we can generally categorize them into two types based on how credentials are presented in the programming code.
- Basic authentication – credentials are presented using plain text
- Token-based authentication, including API keys(access token) – credentials are presented using unique strings.
These methods are commonly used in various Cisco RESTful APIs.
Basic authentication
Basic Authentication is a widely used authentication method in RESTful APIs. In Basic Authentication, the client sends the username and password as a Base64 encoded string in an HTTP request. It is simple but not very secure, as credentials, for instance, are in plain text within the code. We need to ensure that the connection between the client and the server is secure; otherwise, the credentials can be intercepted.
Using Basic authentication in Python is simple. With the requests library, we just need to pass the username and password as parameters when making the API request.
Use Cisco Identity Services Engine (ISE) API as an example, the Python code snippet looks like this :
import requests
from requests.auth import HTTPBasicAuth
auth=HTTPBasicAuth(<username>, <password>)
response = requests.get("https://{host}:{port}/ers/config/endpoint", auth=auth, verify=False)
In fact, HTTP Basic Auth is so common that Python Requests library provides a handy shorthand for using it. The code above can be implemented as follows.
import requests
response = requests.post("https://{host}:{port}/ers/config/endpoint", auth=(<username>, <password>), verify=False)
Token-based authentication
Token-based authentication is usually implemented by requiring clients to obtain a token as proof of authorization. This token is often obtained through secure access to a web portal or by using API calls. Common token-based authentication schemes include JSON Web Tokens (JWT), OAuth2 access tokens, and API keys.
When working with APIs in Python, we use tokens in different ways depending on the type of tokens. For example, Cisco Webex APIs, you obtain the token through Webex Developer Portal by opening the Accounts and Authentication section of the developer documentation. Once you obtained your token, you can use it in Python by including it in the headers of each request as the <'authorization': 'Bearer ' + access_token> key-value pair.
import requests
headers = { 'Content-Type': 'application/json', 'authorization': 'Bearer ' + access_token }
response = requests.get('https://webexapis.com/v1/messages?roomId=<room id>',headers= headers, verify = False)
print (response.text)
Typically, API keys and access tokens are included in request header, but they can be used in different ways as well. For example, with the Cisco Panoptica API, we obtain two keys from its web portal and pass them as parameters in Escher authentication when making the API request.
Some APIs utilize both authentication methods we mentioned to make an API request. For instance, with the well-known Cisco DNAC APIs, the API user must use Basic authentication method to make an initial API request and obtain a token, and then use token to make subsequent API calls.
import requests
import json
response = requests.post("https://"+dnacip+"/dna/system/api/v1/auth/token", auth=(<username>, <password>), verify=False)
token = response.json()["Token"]
headers = {"X-Auth-Token": token,"Content-Type":"application/json"}
resonsep = requests.get(("https://"+dnacip+"/dna/system/api/v1/network-device",headers=headers,verify = False)
Notice that above code snippet, there is no <'authorization': 'Bearer ' + token> key-value pair in header. Instead, a unique key-value pair <’X-Auth-Token’: token> is used.
When dealing with RESTful API authentication, the common errors we frequently encounter are 401 – Unauthorized and 403- Forbidden. Here is a brief explanation of the difference between 401 and 403
API document is your best friend
When implementing authentication in your code, it is essential to consult the API documentation first. The API documentation should provide you with clear instructions on how to authenticate and use the API properly.
The API documentation should outline the authentication method used by the API and the steps you need to follow. This information will vary depending on the API you are using, so it is essential to read the documentation carefully.
Developers at Cisco constantly working on the improving Cisco APIs, which may result in changes to the implementation of API authentication. It is always best to consult the latest official API documentations.
Cisco Developer Web portal provides most of Cisco APIS Documents and authentication-related sites, code, learning labs, etc., for your reference.
