Authentication

Introduction

Catalyst Center REST API uses token-based authentication over HTTPS. Initial authentication involves sending base64-encoded credentials via Basic Authentication to the authentication endpoint, which returns an access token. This token must be included in the X-Auth-Token header for all subsequent API requests. Tokens have a limited lifespan and require re-authentication.

Goal

This guide aims to help you to create a script that authenticates against the Catalyst Center API and obtains the authorization token that is needed to make requests to the API.

Authentication workflow

Endpoints and methods used

  • POST /dna/system/api/v1/auth/token

Note: An authentication endpoint is a specific URL or interface in a system or API where users or devices send their credentials to verify their identity. This endpoint processes the authentication request, validates the credentials, and typically issues an authentication token or grants access based on the verification.

Prerequisites

For this module, it's helpful if you know the basics of Python and REST APIs. If you must catch up, refer to Introduction to Python.

Environment

This guide was developed using:

Authentication

Follow these steps to authenticate:

  • Use Basic Authentication with base64-encoded credentials to request a token.
  • Receive token from the authentication endpoint.
  • Include token in the X-Auth-Token header for all subsequent API requests.

This approach aligns with standard REST API token-based authentication practices, where the initial authentication uses Basic Authentication to obtain a token, and subsequent requests use the token for authorization.

Basic Authentication

Authentication is done by using the Basic authentication scheme, as defined in RFC 7617.

The format of the credentials is USERNAME:PASSWORD and it must be base64 encoded. Then, send the encoded string as part of the Authorization header over clear text. Therefore, it's highly recommended to do this over an HTTPS/TLS connection.

AES Key Encryption

Catalyst Center now supports AES key encryption for token API operation. This optional feature formats the authorization header as a base 64 encoded string of a 256-bits AES key.

The format of the string is CSCO-AES-256 credentials=Base64Encode(AESEncrypt(username:password , aes256 key)).

The AESEncrypt first encrypts the username:password pair with a 256 bits AES key and then Base64Encode encodes the result in base 64 string format.

The AES256 scheme authorizes, as defined in RFC 2617.

Note:

  • You can enable the AES key encryption from the Catalyst Center system configuration.
  • If you disable the AES key encryption from the Catalyst Center system configuration, the default basic authentication is enabled by default.

Token

After successful authentication using Basic Authentication with your credentials, the Catalyst Center REST API issues a token. This token must be included in every subsequent API request as the value of the X-Auth-Token HTTP header to authorize and authenticate those calls. Ensure that each API operation includes this header to maintain session validity and access control.

Validity of a Token

The lifetime of a token is 60 minutes.

When the token expires, the API operation returns a 401 UNAUTHORIZED response code. In such cases, the user must request a new token by initiating the authentication process again.

To authenticate using Postman, see Generating an Authorization Token.

Authentication Code

We create a Python script that authenticates and prints the token necessary for authentication.

We use the Python requests library, importing both the requests library but also the HTTPBasicAuth specifically, which simplifies the Basic Authentication process.

import requests
from requests.auth import HTTPBasicAuth

Next, we import the urllib3 library and call the disable_warnings() function. This is NOT recommended on a production environment. We use it here in the development environment to avoid the warning that we would get of using a self-signed certificate in Catalyst Center.

import urllib3
urllib3.disable_warnings()

Next, we define four general variables of the script:

  • Base URL: IP Address or Fully Qualified Domain Name (FQDN) of the Catalyst Center server
  • Auth URL: API operation endpoint used for authentication
  • Username: Catalyst Center USERNAME
  • Password: Catalyst Center PASSWORD
BASE_URL = 'https://10.10.10.181'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

Finally, you perform the request using POST, which returns a JSON body with the token. Use the verify=False parameter to query a server with a self-signed certificate. In a production environment with a valid certificate generated by a trusted certificate authority, you don't need it.

response = requests.post(baseUrl + authUrl, auth=HTTPBasicAuth(USERNAME, PASSWORD), verify=False)
print(response.json()['Token'])

Code

The repository for this guide is here. The complete code appears as below:

# Module import
import requests
from requests.auth import HTTPBasicAuth

# Disable SSL warnings. Not needed in production environments with valid certificates
import urllib3
urllib3.disable_warnings()

# Authentication
BASE_URL = 'https://<IP Address>'
AUTH_URL = '/dna/system/api/v1/auth/token'
USERNAME = '<USERNAME>'
PASSWORD = '<PASSWORD>'

response = requests.post(BASE_URL + AUTH_URL, auth=HTTPBasicAuth(USERNAME, PASSWORD), verify=False)
print(response.json()['Token'])