cancel
Showing results for 
Search instead for 
Did you mean: 
cancel
Announcements
Community Live- Tenant Routed Multicast in VXLAN EVPN Fabric

Cisco HyperFlex API Token Manager

151
Views
0
Helpful
0
Comments

Cisco HyperFlex API Token Manager

published

Cisco HyperFlex API Token Manager provides the ability to automate the creation, validation and renewal of HyperFlex API tokens. Basic administration of HyperFlex API tokens is also available with easy to use Python functions that simplify obtaining, refreshing, revoking, and validating tokens.

The Cisco HyperFlex API Token Manager can be used as a solution to work with the HyperFlex AAA (Authentication, Authorization and Accounting) API rate limit introduced in HyperFlex 4.0(2a).

The Cisco HyperFlex API Token Manager can be found on the Cisco DevNet Code Exchange here or directly from GitHub at https://github.com/ugo-emekauwa/hx-api-token-manager.

Prerequisites:

  1. Python 3 installed, which can be downloaded from https://www.python.org/downloads/.
  2. Clone or download the Cisco HyperFlex API Token Manager repository by using the GitHub Clone or download link on the main repository web page or by running the following command:
    git clone https://github.com/ugo-emekauwa/hx-api-token-manager
    
  3. Install the required Python modules requests and urllib3. The requirements.txt file in the repository can be used by running the following command:
    python -m pip install -r requirements.txt
    
  4. The IP address of the targeted Cisco HyperFlex system.
  5. User credentials with administrative rights on the targeted Cisco HyperFlex system.

After fulfilling the requirements listed in the Prerequisites section, hx_api_token_manager.py can be ran directly from your IDE or imported into another module.

How to Use:

Basic Functions

The Cisco HyperFlex API Token Manager module contains seven functions for managing HyperFlex API tokens. Here are four core basic functions that provide the ability to obtain, refresh, validate and revoke HyperFlex API tokens.

  • Obtain Access Tokens

    obtain_token(ip,username,password)

    The function obtain_token() obtains a new HyperFlex API access token. A HyperFlex API access token authorizes API operations on a HyperFlex cluster.

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.
      • username - The username credentials that will be used to log into HyperFlex. The value must be a string.
      • password - The password credentials that will be used to log into HyperFlex. The value must be a string.
    • What the Function Returns:

      A HyperFlex API access token, refresh token and token type that have been granted as key-value pairs in a dictionary.

    • Example Usage:

      (1). First let's create variables to hold the values for the obtain_token() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 1 - Argument Variables for obtain_token() Function

      (2). Now let's run the obtain_token() function with the variables as the arguments. Here we can see that a dictionary containing a new HyperFlex API token has been returned as highlighted.

      Figure 2 - Results from obtain_token() Function - Return Highlighted

      (3). Another option is to assign the obtain_token() function to a variable. The returned HyperFlex API token dictionary will be directly held by the variable for easy reusability later with other functions.

      Figure 3 - Assign obtain_token() Function to Variable

      (4). Here we can see that the token1 variable now holds the returned HyperFlex API token dictionary.

      Figure 4 - Assign obtain_token() Function to Variable - Value Returned

  • Refresh Access Tokens

    refresh_token(ip,hx_api_token)

    The function refresh_token() refreshes or renews a HyperFlex API access token. A new HyperFlex API access token is obtained without the need to provide username and password credentials.

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.
      • hx_api_token - A dictionary value for a granted HyperFlex AAA token containing the following keys:
        • "access_token" - An access token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The access token is used to authorize API operations by properly authenticated users.
        • "refresh_token" - A refresh token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The refresh token can be used to obtain a new access token without the need to re-provide HyperFlex username and password credentials.
        • "token_type" - A token type obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The token type value is "Bearer".
    • What the Function Returns:

      A HyperFlex API access token, refresh token and token type that have been granted as key-value pairs in a dictionary.

    • Example Usage:

      (1). First let's create variables to hold the values for the refresh_token() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 5 - Argument Variables for refresh_token() Function

      (2). Now let's run the refresh_token() function with the variables as the arguments. Here we can see that a dictionary containing a new HyperFlex API token has been returned as highlighted.

      Figure 6 - Results from refresh_token() Function - Return Highlighted

      (3). Here is a comparison of the older HyperFlex API token held by the token1 variable and the new replacement HyperFlex API token returned by the refresh_token() function.

      Figure 7 - Results from refresh_token() Function Comparison - Values Highlighted

  • Validate Access Tokens

    validate_token(ip,hx_api_token,scope="READ")

    The function validate_token() validates a HyperFlex API access token. A newly issued HyperFlex API access token is valid for 18 days from the point of creation. The validate_token() function can be used to check if an issued HyperFlex API access token is still valid.

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.
      • hx_api_token - A dictionary value for a granted HyperFlex AAA token containing the following keys:
        • "access_token" - An access token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The access token is used to authorize API operations by properly authenticated users.
        • "refresh_token" - A refresh token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The refresh token can be used to obtain a new access token without the need to re-provide HyperFlex username and password credentials.
        • "token_type" - A token type obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The token type value is "Bearer".
      • scope - (Optional) The scope of the validate access token operation. Providing this argument is optional. The value must be a string. The options are "READ" or "MODIFY". The default value is "READ".
    • What the Function Returns:

      The Boolean value True is returned for a successful validation. The Boolean value False is returned if the validation fails.

    • Example Usage:

      (1). First let's create variables to hold the values for the validate_token() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 8 - Argument Variables for validate_token() Function

      (2). Now let's run the validate_token() function with the variables as the arguments. Here we can see that a successful validation has occurred and the Boolean value True been returned as highlighted.

      Figure 9 - Results from validate_token() Function - Return Highlighted

  • Revoke Tokens

    revoke_token(ip,hx_api_token)

    The function revoke_token() revokes a HyperFlex API access token. A newly issued HyperFlex API access token is valid for 18 days from the point of creation. The revoke_token() function can be used to revoke a previously issued HyperFlex API access token for any reason (e.g. security, etc.).

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.
      • hx_api_token - A dictionary value for a granted HyperFlex AAA token containing the following keys:
        • "access_token" - An access token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The access token is used to authorize API operations by properly authenticated users.
        • "refresh_token" - A refresh token obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The refresh token can be used to obtain a new access token without the need to re-provide HyperFlex username and password credentials.
        • "token_type" - A token type obtained from the HyperFlex API AAA (Authorization, Accounting and Authentication). The token type value is "Bearer".
    • What the Function Returns:

      The Boolean value True is returned for a successful revocation. The Boolean value False is returned if the revocation fails.

    • Example Usage:

      (1). First let's create variables to hold the values for the revoke_token() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 10 - Argument Variables for revoke_token() Function

      (2). Now let's run the revoke_token() function with the variables as the arguments. Here we can see that a successful revocation has occurred and the Boolean value True been returned as highlighted.

      Figure 11 - Results from revoke_token() Function - Return Highlighted

Advanced Functions

The Cisco HyperFlex API Token Manager module contains three additional functions that provide the ability to automate the creation, validation and renewal of access tokens. Offline token use is also provided among other features.

  • Automated Management of Token Files

    manage_token_file(ip,username,password,file_path,data="token",overwrite=True)

    The function manage_token_file() creates or loads an XML file containing a HyperFlex API token and then validates the loaded token data. If the loaded HyperFlex API access token is not valid, a new access token will be automatically obtained. If there is a no HyperFlex API token file present in the provided file path, a new token file will be automatically created.

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.

      • username - The username credentials that will be used to log into HyperFlex. The value must be a string.

      • password - The password credentials that will be used to log into HyperFlex. The value must be a string.

      • file_path - The file name and storage location to write a HyperFlex API token file. The value must be a string. An example value is "c:\\folder\\file.xml".

      • data - (Optional) The data from a HyperFlex API token file that is returned by the manage_token_file() function. Providing this argument is optional. The default value of "token" is set, which returns the access token, refresh token, and token type as a dictionary. The user provided value must be a string. See the following list for the options available for the data argument and the returned value:

        • "token" - Returns a dictionary with the access token, refresh token, and token type.
        • "access_token" - Returns a string value of only the access token.
        • "refresh_token" - Returns a string value of only the refresh token.
        • "token_type" - Returns a string value of only the token type.
        • "human_readable_time" - Returns a string value of the HyperFlex API token file creation time in a human-readable format.
        • "unix_timestamp_time" - Returns a string value of the HyperFlex API token file creation time in Unix timestamp format.
        • "source_module" - Returns a string value of the source module used to create the HyperFlex API token file.

        NOTE: For automatic validation and renewals of HyperFlex API tokens to occur, the data argument must be set to "token" (default), "access_token", or "refresh_token".

      • overwrite - (Optional) The option to overwrite any pre-existing file at the provided file path value given to the file_path argument. Providing this argument is optional. If the argument is set to the Boolean value True, any pre-existing token file will be automatically overwritten. If the argument is set to the Boolean value False, the manage_token_file() function will stop and not proceed with creating a new token file if a pre-existing token file is already in place at the given file path location. The default value is True.

        NOTE: For automatic validation and renewals of HyperFlex API tokens to occur, the overwrite argument must be set to the Boolean value True (default). Setting the overwrite argument to the Boolean value False will disable the ability to update pre-existing HyperFlex API token files.

    • What the Function Returns:

      The return is based on the value of the data argument. If the default value of "token" is set, the access token, refresh token, and token type will be returned as a dictionary. See the following list to see the options available for the data argument and the returned value:

      • "token" - Returns a dictionary with the access token, refresh token, and token type.
      • "access_token" - Returns a string value of only the access token.
      • "refresh_token" - Returns a string value of only the refresh token.
      • "token_type" - Returns a string value of only the token type.
      • "human_readable_time" - Returns a string value of the HyperFlex API token file creation time in a human-readable format.
      • "unix_timestamp_time" - Returns a string value of the HyperFlex API token file creation time in the Unix timestamp format.
      • "source_module" - Returns a string value of the source module used to create the HyperFlex API token file.
    • Example Usage:

      (1). First let's create variables to hold the values for the manage_token_file() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 12 - Argument Variables for manage_token_file() Function

      (2). Now let's run the manage_token_file() function with the variables as the arguments. Here we can see that a dictionary containing a new HyperFlex API token has been returned as highlighted.

      Figure 13 - Results from manage_token_file() Function - Return Highlighted

      (3). Here we can see a sample HyperFlex API token file and the available data in XML format created by the manage_token_file() function. The XML file is held at the storage location given in the file_path argument.

      Figure 14 - Sample XML File Created by manage_token_file() Function

      (4). Another option is to assign the manage_token_file() function to a variable. The returned HyperFlex API token dictionary will be directly held by the variable for easy reusability later with other functions.

      Figure 15 - Assign manage_token_file() Function to Variable

      (5). Here we can see that the token1 variable now holds the returned HyperFlex API token dictionary.

      Figure 16 - Assign manage_token_file() Function to Variable - Value Returned

      (6). Now let's run the manage_token_file() function with the data argument set to "access_token". Here we can see that only the HyperFlex API access token has been returned as highlighted.

      Figure 17 - Results from manage_token_file() Function - access_token Returned

      (7). Now let's run the manage_token_file() function with the data argument set to "refresh_token". Here we can see that only the HyperFlex API refresh token has been returned as highlighted.

      Figure 18 - Results from manage_token_file() Function - refresh_token Returned

      (8). Now let's run the manage_token_file() function with the data argument set to "token_type". Here we can see that only the HyperFlex API token type has been returned as highlighted.

      Figure 19 - Results from manage_token_file() Function - token_type Returned

      (9). Now let's run the manage_token_file() function with the data argument set to "human_readable_time". Here we can see that only the HyperFlex API token creation time in a human-readable format has been returned as highlighted.

      Figure 20 - Results from manage_token_file() Function - human_readable_time Returned

      (10). Now let's run the manage_token_file() function with the data argument set to "unix_timestamp_time". Here we can see that only the HyperFlex API token creation time in the Unix timestamp format has been returned as highlighted.

      Figure 21 - Results from manage_token_file() Function - unix_timestamp_time Returned

      (11). Now let's run the manage_token_file() function with the data argument set to "source_module". Here we can see that only the source module from which the manage_token_file() function was called has been returned as highlighted.

      Figure 22 - Results from manage_token_file() Function - source_module Returned

  • Creation of Token Files

    create_token_file(ip,username,password,file_path,overwrite=True)

    The function create_token_file() creates an XML file containing a newly issued HyperFlex API token.

    NOTE: For automated creation, validation and renewal of HyperFlex API token files, the manage_token_file() function should be used. The create_token_file() function will only create new HyperFlex API token files.

    • The Available Function Arguments:

      • ip - The targeted HyperFlex Connect or Cluster Management IP address. The value must be a string.
      • username - The username credentials that will be used to log into HyperFlex. The value must be a string.
      • password - The password credentials that will be used to log into HyperFlex. The value must be a string.
      • file_path - The file name and storage location to write a HyperFlex API token file. The value must be a string. An example value is "c:\\folder\\file.xml".
      • overwrite - (Optional) The option to overwrite any pre-existing file at the provided file path value given to the file_path argument. Providing this argument is optional. If the argument is set to the Boolean value True, any pre-existing token file will be automatically overwritten. If the argument is set to the Boolean value False, the create_token_file() function will stop and not proceed with creating a new token file if a pre-existing token file is already in place at the given file path location. The default value is True.
    • What the Function Returns:

      The file path of the new HyperFlex API token file in XML format is returned if creation was successful. The value None is returned if creating a HyperFlex API token file failed.

    • Example Usage:

      (1). First let's create variables to hold the values for the create_token_file() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 23 - Argument Variables for create_token_file() Function

      (2). Now let's run the create_token_file() function with the variables as the arguments. Here we can see that a new HyperFlex API token file has been created. The storage location of the new HyperFlex API token file has been returned as highlighted.

      Figure 24 - Results from create_token_file() Function - Return Highlighted

      (3). Here we can see a sample HyperFlex API token file and the available data in XML format created by the create_token_file() function. The XML file is held at the storage location given in the file_path argument.

      Figure 25 - Sample XML File Created by create_token_file() Function

      (4). Now let's run the manage_token_file() function with the overwrite argument set to False. Here we can see that the pre-existing HyperFlex API token file was not overwritten.

      Figure 26 - Results from create_token_file() Function - overwrite Argument Set to False

  • Loading Token Files

    load_token_file(file_path,data="token")

    The function load_token_file() loads data from an XML file containing a HyperFlex API token.

    NOTE: For automated creation, validation and renewal of HyperFlex API token files, the manage_token_file() function should be used. The load_token_file() function will only load data from pre-existing HyperFlex API token files.

    • The Available Function Arguments:

      • file_path - The file name and storage location from which to load a HyperFlex API token file. The value must be a string. An example value is "c:\\folder\\file.xml".
      • data - (Optional) The data from a HyperFlex API token file that is returned by the load_token_file() function. Providing this argument is optional. The default value of "token" is set, which returns the access token, refresh token, and token type as a dictionary. The user provided value must be a string. See the following list for the options available for the data argument and the returned value:
        • "token" - Returns a dictionary with the access token, refresh token, and token type.
        • "access_token" - Returns a string value of only the access token.
        • "refresh_token" - Returns a string value of only the refresh token.
        • "token_type" - Returns a string value of only the token type.
        • "human_readable_time" - Returns a string value of the HyperFlex API token file creation time in a human-readable format.
        • "unix_timestamp_time" - Returns a string value of the HyperFlex API token file creation time in Unix timestamp format.
        • "source_module" - Returns a string value of the source module used to create the HyperFlex API token file.
    • What the Function Returns:

      The return is based on the value of the data argument. If the default value of "token" is set, the access token, refresh token, and token type will be returned as a dictionary. See the following list to see the options available for the data argument and the returned value:

      • "token" - Returns a dictionary with the access token, refresh token, and token type.
      • "access_token" - Returns a string value of only the access token.
      • "refresh_token" - Returns a string value of only the refresh token.
      • "token_type" - Returns a string value of only the token type.
      • "human_readable_time" - Returns a string value of the HyperFlex API token file creation time in a human-readable format.
      • "unix_timestamp_time" - Returns a string value of the HyperFlex API token file creation time in Unix timestamp format.
      • "source_module" - Returns a string value of the source module used to create the HyperFlex API token file.
    • Example Usage:

      (1). First let's create variables to hold the values for the load_token_file() function arguments. Using variables is not required, but provides for easier readability and the variables can be re-used again at a later time if needed.

      Figure 27 - Argument Variables for load_token_file() Function

      (2). Now let's run the load_token_file() function with the variables as the arguments. Here we can see that a dictionary containing a new HyperFlex API token has been returned as highlighted.

      Figure 28 - Results from load_token_file() Function - Return Highlighted

      NOTE: For examples of the output from the various optional values of the data argument, see the Example Usage section for the manage_token_file() function. The type of outputs are the same for the load_token_file() function.

Notes:

  • For setups where logging is desired, a version of the Cisco HyperFlex API Token Manager that has been modified to output to a log file is available in the logging-version folder of this repository as hx_api_token_manager_logging.py. Before use, manually edit the hx_api_token_manager_logging.py file to add a log file location or import hx_api_token_manager_logging into another module where the log file location has already been set.

Related Tools:

Here are similar tools to help manage Cisco HyperFlex training, demonstration and development environments.

Author:

Ugo Emekauwa

Contact Information:

uemekauw@cisco.com or uemekauwa@gmail.com

CreatePlease to create content
Content for Community-Ad

Cisco COVID-19 Survey