Authorization
=============

Our authorization is based on `OAUTH2`_, with MINT as `client` and Platform as `resource owner`,
`auth server` and `resource server`; Thus, it is Platform responsibility
to provide its customers with the way to authorize MINT to interact with his account
and data processed and retained by Platform. It is necessary, so MINT can fetch, and
process advertisement data of customer, and perform adjustments on customer's behalf.

.. _OAUTH2: https://oauth.net/2/

Customer perspective
--------------------

Process of authorization will look very similar to other services, such as Google.
For example, customer whats to authorize MINT to `collect`, `process` and `adjust`
his data from Platform, customer will be redirected to Platform authorization page,
where he would confirm his identity and allow or disallow Platform to receive requests
from MINT on behalf of customer; After authorizing MINT on Platform, customer will be
redirected back to MINT UI, where he would be able to access his data from Platform
and adjust his advertisement campaigns from platform (MINT does not authomatic
adjustments, we can only read, process and display the data, also MINT can ``suggest``
changes to his advertisement campaigns at Platform that customer may or may not apply).

Programmer perspective
----------------------

Front-end
^^^^^^^^^

FE job is to provide a convenient UI for customer, so he could authorize MINT to access
his data at Platform.

Platform FE
'''''''''''

Platform FE will have to provide safe widget/page where customer can safely enter his
credentials or otherwise authorize MINT to access his data at Platform. After MINT is
being authorized to interact with Platform at customer's behalf Platform widget/page
is to provide `Authorization Code` for MINT to complete integration process.

MINT FE
'''''''

MINT FE will have to provide safe and convenient UI for customer to browse possible
platform integrations and grant customer the ability to authorize MINT to integrate
with any of them. When customer would decide to integrate with certain Platform, he
will click on corresponding button and will delivered to Platform authorization page/widget,
where he can authorize MINT to access his data at given Platform. After MINT is authorized,
Platform is to provide `Authorization Code`. When `Authorization Code` is obtained
by MINT FE, it will be sent for MINT BE for farther processing and completion of
integration.

Back-end
^^^^^^^^

Platform BE
'''''''''''

Platform BE is to receive and validate customer credentials and permissions, if
everything is ok,  it will generate and send `Authorization Code` as response.
Also, Platform BE will receive requests with their `Authorization Code` from MINT BE,
in Platform BE will validate such requests, and if `Authorization Code` is valid,
will send access and refresh_token in response. When MINT BE will make request
for fresh `access_token`,  Platform BE is to validate `refresh_token` and if its valid,
Platform BE will send fresh `access_token` in response.

.. warning::

    `refresh_token` can only be used to obtain `access_token`, while full customer
    authorization process is the only way to obtain `refresh_token`, it suppose
    to be long-living token, for the sake of customer convenience.

.. warning::

    `refresh_token` should have long lifespan, before expire lifetime of should be
    prolonged with each "get fresh access_token". There could also be a limit to
    lifetime extension.

MINT BE
'''''''

MINT BE is to receive `Authorization Code` to exchange it for `access_token` and
`refresh_token`, when tokens received MINT BE will encrypt and save them for farther
usage. If `access_token` expired, MINT BE will use `refresh_token` to  request fresh
`access_token` from Platform BE.

.. warning::

    `refresh_token` can only be used to obtain `access_token`, while full customer
    authorization process is the only way to obtain `refresh_token`, it suppose
    to be long-living token, for the sake of customer convenience.

.. warning::

    `refresh_token` should have long lifespan, before expire lifetime of should be
    prolonged with each "get fresh access_token". There could also be a limit to
    lifetime extension.