.. include:: /Includes.rst.txt
.. _rest-authentication:

======================
Login / Authentication
======================

.. toctree::
   :hidden:
   :glob:

Introduction
============

The authorization against the EOS Rest API is done using an :ref:`Auth header<auth-header>`. To get the proper token, you need to authenticate against the EOS server, which is beeing done with two succeeding requests. 

1. First we need to :ref:`request a login token<request-login-token>`
2. Second we need to :ref:`authenticate<authentication>` to get a session key for further authorization, that
3. Will be used in our :ref:`Authorization header<auth-header>`.

Parameters that will be used
----------------------------

.. code:: typescript

    - DOMAIN: string // windows domain - optional, example: "domain" or ""
    - USERNAME: string // user name - e.g.: "swojtowicz"
    - USERPASS: string // user password - e.g.: "secret"
    - REST_URL: string // rest URL - e.g.: "https://server:port/rest"
    - PASSPHRASE: string // will be built using request answers
    - SESSIONKEY: string // will be returned in an answer

.. _request-login-token:

1. Requesting a login token
===========================

Parameters used
---------------

.. code:: typescript

    - DOMAIN: string // windows domain - optional, example: "domain" or ""
    - USERNAME: string // user name - e.g.: "swojtowicz"

URL
---

.. code:: console

   auth/user/request_login_token/domain=[DOMAIN]&login=[USERNAME]

Response
--------

.. code:: typescript

    { 
      message: string, // token to generate passphrase
      session_key: null,
      type: [Success | WrongPassword | CertificateError | UserInactive | UserNotFound | InternalError],
      user_principal: null
    }

Example request
---------------

.. code:: console

   https://server.test:1111/rest/auth/user/request_login_token/domain=&login=swojtowicz

Example answer
--------------

.. code:: typescript

    { 
      message: "token123",
      session_key: null,
      type: "Success",
      user_principal: null
    }

Usage of the response
---------------------

Provided your response has type = "Success", you can now generate a passphrase as follows:

.. _passphrase-generation:

.. code:: typescript

    let PASSPHRASE = base64encode('{"token": "token123", "password": "secret"}');
    //             = eyJ0b2tlbiI6InRva2VuMTIzIiwicGFzc3dvcmQiOiJnZWhlaW0ifQ==

.. _authentication:

2. Authentication
==================

Parameters used
---------------

.. code:: typescript

    - USERNAME: string
    - PASSPHRASE: string // base64 encoded passphrase like mentioned above

URL
---

.. code:: console

    auth/user/login/domain=&login=[USERNAME]&passphrase_encoded=false&passphrase=[PASSPHRASE]

Answer
------

.. code:: typescript

    {
      message: null,
      session_key: string, // needed for further requests
      type: [Success | WrongPassword | CertificateError | UserInactive | UserNotFound |
    InternalError],
      user_principal: string // user name
    }

Exmaple request
---------------

.. code:: console

    https:// server:port/rest/auth/user/login/domain=&login=swojtowicz&passphrase_encoded=false&passphrase=eyJ0b2tlbiI6InRva2VuMTIzIiwicGFzc3dvcmQiOiJnZWhlaW0ifQ==

Example response
----------------

.. code:: typescript

    {
      type: "Success", 
      user_principal: "swojtowicz", 
      session_key: "1bpb5fvrat7rlpb81he6oq10f4", 
      message: null
    }

Usage of the response
---------------------

Provided your response answer type was "Success", you can and must now use session_key for follow up requests as follows.

.. _auth-header:

3. Authorization Header
=======================

To be recognized in follow up requests you have to send an authorization header with each request using given format:

.. code:: typescript

    Authorization: "Basic " + base64encode([USERNAME] + ":" + [SESSIONKEY])

Example request authorization header:

.. code:: typescript

    Authorization: "Basic " + base64encode("swojtowicz:1bpb5fvrat7rlpb81he6oq10f4")
    // Authorization: "Basic c3dvanRvd2ljejoxYnBiNWZ2cmF0N3JscGI4MWhlNm9xMTBmNA=="