=====
Usage
=====

Preparations
============
Before using the application, user has to acquire an Offce 365 license
that contains OneDrive application and then make some configuration
adjustments.

Acquiring Office 365 license
----------------------------
This could be done on `office.com <https://www.office.com/>`_.

Configuring Office 365
----------------------

1. After you acquired the license and entered your account, you should see the
   home page. Click on the "Admin" button.

    .. image:: images/x0ivvzfTY3.png
       :width: 50%

2. Then click on "Active users".

    .. image:: images/x0ivvzfTY3.png
       :width: 50%

3. Find user, that you want to use for accessing OneDrive and click on it.

    .. image:: images/xQoJn5o6p5.png
       :width: 50%

    .. tip:: You can setup a user with guest-status so that the application
             won't have admin-access to your Office 365.

4. Click on "Edit" button in the "Product licenses" row.

    .. image:: images/IJsbBP1R7F.png
       :width: 50%

5. Ensure the license is turned on for the user.

    .. image:: images/HCkFEhqKMO.png
       :width: 50%

6. Open the home page of Office 365 as the picked user and click on
   OneDrive application button (sometimes it might be required to force
   Office 365 to provision it).

    .. image:: images/7NeUi6xcN2.png
       :width: 50%

7. Then, as an admin user, go to the home page and click on "Admin" button
   again as in step 1..
8. Click on "Azure Active Directory".

    .. image:: images/HhgXv6QXCH.png
       :width: 50%

9. On the newly opened page click on "Azure Active Directory".

    .. image:: images/WjLV4B5gqf.png
       :width: 50%

10. Click on "App registrations".

    .. image:: images/cp87R3NF_r.png
       :width: 50%

11. Click on "New registration".

    .. image:: images/58TDQFxqko.png
       :width: 50%

.. _step-12:

12. Fill all the necessary fields:

      - **Name** - could be arbitrary.
      - **Supported account types** - choose according to your needs. You can
        click on "Help me choose..." to get some guiding information.
      - **Redirect URI (optional)** - put something like
        ``http://localhost:8080`` and remember the value.

    and then click on "Register".

    .. image:: images/rJZ866FJGE.png
       :width: 50%

13. In the opened list of registered applications click on the one
    that was just created.

    .. image:: images/SRmmhZQC4A.png
       :width: 50%

14. Click on "View API permissions" then on "Add a permission" then on
    "Microsoft Graph" then on "Delegated permissions".

    .. image:: images/5GATjmPmsl.png
       :width: 50%

    .. image:: images/G3NDpB3AjM.png
       :width: 50%

    .. image:: images/fTKgbkipLK.png
       :width: 50%

    .. image:: images/jYRHbEx6VF.png
       :width: 50%

15. Find and check ``"``Files.ReadWrite.All``"`` permission or another
    permission that grants level of access to the files according to your
    needs. Then click on "Add permissions".

    .. image:: images/oOeS8DHQmZ.png
       :width: 50%

    .. tip:: Check out the permissions reference:
       https://developer.microsoft.com/graph/docs/concepts/
       permissions_reference

.. _step-16:

16. Return to the application page as in step 13. and click on "Overview".
    Find "Application (client) ID" field and remember the value.

    .. image:: images/vMU0E5hQTe.png
       :width: 50%

17. Click on "Certificates & secrets" and then click on "New client secret".
    Then fill the description (could be arbitrary) and choose expiration
    interval. Then click "Add".

    .. image:: images/LWC1XDxAOl.png
       :width: 50%

    .. image:: images/U8iOj1Q16z.png
       :width: 50%

.. _step-18:

18. Copy the value of the newly created secret and save it somewhere.

    .. image:: images/XtGN07ac6U.png
       :width: 50%

Installation
============
Currently the application is only installable as a standard Python package.
Just clone the repository and install it using Pip_::

   git clone https://github.com/AndreiPashkin/onedrive_client.git
   pip install onedrive_client

.. _Pip: https://pip.pypa.io/en/stable/

Authentication
==============
Application requires a cookie to authenticate in Office 365. Go to
https://login.microsoftonline.com/, login with the credentials you want the
application to use and then collect the cookie value for
``login.microsoftonline.com`` domain. It could be done using a debugging proxy
like Fiddler.

Configuration
=============
Here is an example configuration file::

    client_id: <Client ID (see :ref:`step 16 <.. _step-16>`)>
    client_secret: <Client secret (see :ref:`step 18 <.. _step-18>`)>
    redirect_uri: <Redirect URI (see :ref:`step 12 <.. _step-12>`)>
    cookie: <Cookie value (see `Authentication`_)>
    system_directory: <A directory where you want the app to store data and
                       other internally used files.>
    mount_directory: /home/andrei/projects/onedrive/mount
    log_level: <Accepted values are: CRITICAL, ERROR, WARNING, NOTICE, INFO,
                DEBUG, TRACE. Pick "INFO" if not sure.>

Using application
=================
To launch the application simply use a command like this::

    onedrive -c <Path to the config. file> start

Path to the configuration file could be relative to the current working
directory or absolute.