#####################
OAuth2 Authentication
#####################

The OAuth2 Authentication method retrieves a token and uses it as part of the
request. There are several different grant types that affect token's usage.
You must check whether you are using the correct grant type for the given
request.

To use OAuth2 Authentication, you must select "*OAuth2 Authentication*" from
the "Authentication Type" drop-down list.

All OAuth2 requests have some basic requirements when making
the token request.

The required fields include:

  * **Client ID:** This field provides the ClientID (similar to
    username) when requesting a token. This field is required.

  * **Client Secret:** This field provides the secret (similar to
    password) when requesting a token. This field is required.

  * **Access Token URL:** This field provides the URL for generating the
    token in the data request. This field is required.

  * **Delay Time to Next Request (seconds):** This field provides how long
    to wait (in seconds) between failed requests. If the value is 0, there
    will not be a retry between failed requests. Default: 0. This field is
    optional.

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

  * **Token Format:** This field describes how 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 optional.

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

  * **Client auth method:** This field states how the Client ID and Client
    Secret are sent to the token server. Basic Authentication utilizes the
    Authorization Header while Post Body adds this information into the
    request's body. This field is required.

  * **Token Refresh Implementation:** This field allows the token to be
    expired within ScienceLogic. This enables the Snippet Framework to
    automatically request a new token before the current token is expired.
    If *Static* is selected, a new field will appear where the time-to-live
    will be specified (in seconds). This field is optional.


**************
Resource Owner
**************

The OAuth2 Authentication method can use the Resource Owner grant type to
enable token generation for a given username, password, and scopes.

To use this grant type, you must select the
*"Resource Owner Password Credentials"* option from the "OAuth2 Grant Type"
drop-down list.

The required fields for Resource Owner include:

 * **Resource Owner Username:** This field states the username that
   will own the token.  This field is required.

 * **Resource Owner Password:** This field states the password for
   the given username of the token.  This field is required.

 * **Token Scopes:** This field supplies all scopes that are required
   to make your data call. If you require multiple scopes, refer to your token
   server on how to supply this information. This field is optional.

 * **Additional body Parameters:** This field allows for any additional
   parameters to be included with the token request. This value should
   be a valid JSON dictionary. This field is optional.

Example
=======

You must make a request to a data server that requires a
token from OAuth2/Resource Owner. The data server expects
the header ``Auth: Bearer <token>``. The token server requires
the client credentials as part of Basic Authentication.

The token server generates the tokens at ``https://token.info`` with
"Client ID" of *my_client_id*, "Client Secret" of *my_client_secret*,
"Owner Credential" of *OwnerUser/OwnerPass*, and "Token scopes" of
*"Scope3, Scope4"*.

The returned format of this generation:

.. code:: javascript

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

To configure OAuth2/Resource Owner, these must be configured:

 * Client ID: my_client_id
 * Client Secret: my_client_secret
 * Access Token URL: https://token.info
 * Request Header: Auth
 * Token Format: Bearer {}
 * Response Token Key: token
 * Client auth method: Basic Auth
 * Resource Owner Username: OwnerUser
 * Resource Owner Password: OwnerPass
 * Token Scopes: Scope3, Scope4


******************
Client Credentials
******************

The Client Credentials grant type allows the generation of
a token for a given set of scopes.

To use this grant type, you must select the
*"Client Credentials"* value from the "OAuth2 Grant Type"
drop-down list.

The field included in Client Credentials:

 * **Token Scopes:** This field supplies all scopes that are required
   to make your data call. If you require multiple scopes,
   refer to your token server on how to supply this information.
   This field is optional.

Example
=======

You must make a request to a data server that requires a
token from OAuth2/Client Credentials. The data server expects
the header ``Auth: Bearer <token>``. The token server requires
the client credentials within the body of the request.

The token server generates the tokens at ``https://token.info`` with
"Client ID" of *my_client_id*, "Client Secret" of *my_client_secret*,
"Owner Credential" of *OwnerUser/OwnerPass*, "Token Scopes" of
"*Scope3, Scope4*".

The returned format of this generation:

.. code:: javascript

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


To configure OAuth2/Resource Owner, these must be configured:

 * Client ID: my_client_id
 * Client Secret: my_client_secret
 * Access Token URL: https://token.info
 * Request Header: Auth
 * Token Format: Bearer {}
 * Response Token Key: token
 * Client auth method: Post Body
 * Token Scopes: Scope3, Scope4