OneDrive
========

.. note::
    It's required to install ``email`` from :ref:`Optional dependencies` section.


.. note::
    | For onedrive you need to specify authorization, you need to create & configure new application with the Microsoft identity platform. By the following steps:
    | 1. `Register an application <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application>`_
    | 2. (Optional) In case of using Public(Delegated) Authorization option, you have to enable **Allow public client flows** in **Authentication** section
    | 3. `Add credentials <https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-credentials>`_, we currently support only Client's Secret
    | 4. `Add corresponding permissions for OneDrive <https://learn.microsoft.com/en-us/graph/api/driveitem-list-permissions?view=graph-rest-1.0&tabs=http#permissions>`_, in section **Permissions**.

    | `Application permissions <https://learn.microsoft.com/en-us/graph/auth-v2-service>`_ - App runs as a background service or daemon without a signed-in user. But has usually access to all resources of which some can't be limited.
    | `Delegated permissions <https://learn.microsoft.com/en-us/graph/auth-v2-user>`_ - App needs to access the API as the signed-in user. Thus can't access resources that the user doesn't have access to.

    .. list-table:: Onedrive permissions list - one should be sufficient.
       :widths: 40 30 30 30
       :header-rows: 1

       * - Permission
         - Application
         - Delegated
         - Can be limited
       * - | ``Files.Read.All``
           | Read access only
         - ✅
         - ✅
         - ❌
       * - | ``Files.ReadWrite.All``
           | Read and write access
         - ✅
         - ✅
         - ❌
       * - | ``Sites.Read.All``
           | Access Sharepoint - Read only
         - ✅
         - ✅
         - ❌
       * - | ``Sites.ReadWrite.All``
           | Access Sharepoint - Read and Write
         - ✅
         - ✅
         - ❌
       * - | ``Sites.Selected``
           | Access Sharepoint - Configurable Read / Write
         - ✅
         - ❌
         - ✅
       * - | ``User.Read``
           | If you need to get user drive id
         - ✅
         - ✅
         - ❌

    .. warning::
        **Important**, Application permissions allow access to all drives or sites.

        If limiting access is a priority we suggest only using Application permissions with ``Sites.Selected`` which enables limitations to Sharepoint drives.

        Otherwise you need to use Delegated permissions for a user with access to the resources needed. But this is not suitable for business critical applications as the user token can expire and an user must approve the application.


Manager
-------

.. automodule:: aiviro.modules.onedrive
    :members: OneDriveManager, OneDriveScope


Files and Folders
-----------------

.. automodule:: aiviro.modules.onedrive.manager
    :members: OneDriveFile, OneDriveFolder