.. _token-authenticator:

**************************
Token Based Authentication
**************************

The Token Authentication, also known as Token Bearer, method uses an
additional header when passing the request for authentication. This
token is dynamically generated from the ``Token Retrieval Endpoint``.

To use Token Authentication you must select `Token Authentication`
as the value for the `Authentication Type` dropdown.

.. image:: ../../_static/authentication/images/example_token_based.png

The required fields to utilize Token Authentication are as follows:

 * Username

    * This field provides the username when requesting the token from
      ``Token Retrieval Endpoint``. This field is optional.

 * Password

    * This field provides the password when requesting the token from
      ``Token Retrieval Endpoint``. This field is optional.

 * Token Retrieval Endpoint

    * This field provides the URL for generating the token that is used
      in the data request. This field is required.

 * Authorization Header

     * This field describes the name of the header to be sent.
       Default: ``Authorization``. This field is optional.

 * Bearer Token Format

    * This field describes how the content should be sent. The format
      allows for a single substitution for the token. This substitution
      occurs when specifying ``{}`` in the format. For example, if you wanted
      to use ``Bearer <token>`` you would input ``Bearer {}``. Default: ``{}``.
      This field is required.

 * Token Key

    * This field states the key where the token exists in the returned JSON
      dictionary. This field is required.

 * Authentication Failure Retry Time

    * This field identifies the number of seconds the authenticator
      must wait before retrying the authentication upon failure. Default: ``60``.
      This field is optional.

 * Token Refresh Implementation

    * This field allows the selection of the token refreshing strategy.
      There are two options `Static` and `Dynamic`. Default: `Dynamic`.

      * `Dynamic` allows the user to specify the field ``Expiry Time Key``.
        This field is used when retrieving the token's time-to-live
        from the authentication response. The next authentication
        request will occur when the expires time is within two collection
        polling cycles. For example, if a Dynamic Application has a polling
        frequency of 5 minutes. Then a new token will be fetched when the saved
        token's expiration time is less than 10 minutes.

      * `Static` allows the user to specify a recurring time to refresh their
        token (in seconds).

Example
-------
You must make a request to a web server (resource server) that
requires a token from another web server (token server). The
resource server expects the header ``Auth: CoolBeans <token>``.
The token server generates tokens at ``https://token.info``
with the credentials **my_user** / **password4321** and returns the
following format:

.. code:: javascript

    {
        "token": "<the_token_to_use>",
        "expires": "900s"
    }

To configure Token Authentication, the following fields are
required:

 * Username: ``my_user``
 * Password: ``password4321``
 * Token Retrieval Endpoint: ``https://token.info``
 * Token Key: ``token``
 * Authorization Header: ``Auth``
 * Bearer Token Format: ``CoolBeans {}``