x
/
broadview-lib
Code Issues Proposed changes
broadview-lib/doc/auth.md

3.7 KiB
Raw Blame History

Authentication

broadview-lib uses python "requests" module for issuing HTTP 1.1 POST requests to the agent. In some cases, authentication is required by the device. The requests module methods (e.g., post(), get()) support an auth keyword argument which can be used to specify an instance of an object that derives from requests.auth.AuthBase, and handle the tasks related to authentication. More information can be found here: http://docs.python-requests.org/en/master/user/authentication/

In broadview_lib/agentconnection.py we've included support for three such objects:

  • requests.HTTPBasicAuth
  • requests.HTTPDigestAuth
  • SIDAuth

HTTPBasicAuth and HTTPDigestAuth are documented on the Requests page linked to above, and are provided by the requests module. SIDAuth is supplied as a class by broadview-lib in config/siduath.py to provide authentication to switches which are running the ICOS NOS.

Specifying Authentication Settings

To use one of the above authentication methods, you must identify the method, and supply a username and password for the device that you are trying to connect to. There are two methods for doing this supported by broadview-lib:

  • environment variables
  • configuration in /etc/broadviewswitches.conf

Note: if a HTTP 401 error is returned by the agent and WWW-Authenticate header is supplied by the server (as required by RFC 2616) then the authentation method specified in the WWW-Authenticate header is used. Otherwise, the method is determined by looking at either the environment variable or the setting in /etc/broadviewswitches.conf.

The settings file has priority over environment variables. In other words, if both specify a value, the settings file value is used, and the environment variable value will be ignored.

The following sections detail each method.

Authentication Environment Variables

Three environment variables can be used to specify authentication settings:

  • BV_AUTH - a string that specifies the authentication method. Supported values include "basic", for HTTPBasicAuth, "digest", for HTTPDigestAuth, and "sidauth", for SIDAuth authentication. Use this variable only against devices that are not providing a WWW-Authenticate header.
  • BV_USERNAME - a string that contains the username used for authentication
  • BV_PASSWORD - a string that contains the password used for authentication

BV_AUTH is ignored if WWW-Authenticate header is present in the HTTP 401 response.

Each environment variable will be ignored if a corresponding value is present in /etc/broadviewswitches.conf.

Authentication settings in /etc/broadviewswitches.conf

The broadviewswitches.conf was originally designed to provide topology information for the BroadView horizon dashboard in OpenStack. It was extended to support 3 additional settings per switch:

  • auth - a string that specifies the authentication method. Supported values include "basic", for HTTPBasicAuth, "digest", for HTTPDigestAuth, and "sidauth", for SIDAuth authentication. Use this variable only against devices that are not providing a WWW-Authenticate header.
  • username - a string that contains the username used for authentication
  • password - a string that contains the password used for authentication

These settings will override the corresponding environment variables, as defined in the previous section. auth is overridden on a per-response basis if WWW-Authenticate is present in the HTTP 401 response headers.

The following is an example /etc/broadviewswitches.conf file.

[topology]

bst_switches = [ { "ip": "10.14.244.119", "port": 80, \
"description" : "switch 1", "auth": "sidauth", \
"username": "admin", "password": ""}, \
{ "ip": "10.27.31.1", "port": 80, "description" : "switch 2", \
"auth": "sidauth", "username": "admin", "password": "" } ]