Token Based Authentication
--------------------------

This is a heavily utilized authentication mechanism. Unfortunately there is no
set standard that has been widely adopted. The challenge in supporting Token
based authentication is as follows:

#.  There are two different types of requests the first is requesting a token.
    This first request can have several different ways of requesting a token.
    Usually there is a username and password and an endpoint url this is used to
    login and retreive a token. The variations start with exactly how this
    initial authentication occurs. For example the username and password can be
    sent as basic authentication, httpdigest authentication, can send them in the
    query parameters, in the payload or in header.
#.  Next, the response can include tokens in the payload, tokens in the headers
    or cookies. The functioning of the token in terms of how long the token is
    valid and what the process is for getting another token and multiple tokens
    be supported.
#.  Various forms of token can be leveraged such as bearer token or JSON Web Token.
#.  The next step is getting that token into the actual request. The token can be
    sent as query parameters, headers, or cookies.

The current out of the box support, supports token based authentication as
follows (refer to the :ref:`Token Authentication <token-authenticator>` section).

#.  The url request assumes the payload contains the username and password. The
    payload handling can be defined in the credential. Support for the expiry
    time is included and can be static or dynamic. The token must be received
    from the payload as well as the expiry information.
#.  On requests, the token must be sent in a header. The format of the header
    can be defined in the credentials.

While the out of the box solution supports a significant amount of use cases,
there are many use cases where the hooks for Token Authentication can be
leveraged to enable successful authentication. All the hooks for token
authentication are defined in :ref:`Authentication Hooks <authenticator-hooks>`.
The following are the most widely used for Token Authentication:

#.  ``get_token_request_args``: Modifies any sesssion parameters before the
    token request is sent.
#.  ``process_response``: Processes the raw token response.
#.  ``modify_session``: Modifies the HTTP session for authenticated requests.
    For details on each of the hooks refer to
    :ref:`Authentication Hooks <authenticator-hooks>`.

**Examples:**

.. toctree::
  :maxdepth: 1

  examples/token-openstack
  examples/token-sdwan