Cisco HyperFlex API Token Manager

The Cisco HyperFlex API Token Manager is a solution to simplify authentication when automating or integrating with Cisco HyperFlex storage systems. Cisco HyperFlex API Token Manager provides the ability to automate the creation, validation and renewal of HyperFlex API security tokens. Basic administration of HyperFlex API security tokens is also available with easy to use Python functions for obtaining, refreshing, revoking, and validating tokens.

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 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 for installation 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.

    

    (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.

    

    (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.

    

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

    

• 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.

    

    (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.

    

    (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.

    

• 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.

    

    (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.

    

• 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.

    

    (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.

    

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.

    

    (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.

    

    (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.

    

    (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.

    

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

    

    (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.

    

    (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.

    

    (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.

    

    (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.

    

    (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.

    

    (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.

    

• 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.

    

    (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.

    

    (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.

    

    (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.

    

• 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.

    

    (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.

    

    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.

Use Cases:

The Cisco HyperFlex API Token Manager is part of the automation solution used to support and maintain the following Cisco Data Center product demonstrations on Cisco dCloud:

1. Cisco HyperFlex with Hyper-V v1

Cisco dCloud is available at https://dcloud.cisco.com, where product demonstrations and labs can be found in the Catalog.

Related Tools:

Here are similar tools to help administer and manage Cisco HyperFlex and UCS environments.

• Cisco IMM Automation Tools
• HyperFlex Edge Automated Deployment Tool for Cisco Intersight
• HyperFlex Notification Tool for Cisco Intersight
• HyperFlex HTML Plug-In Automated Installer

Author:

Ugo Emekauwa

Contact Information:

[email protected] or [email protected]