Release 2.3.0, README.md updates (examples section), support for client certificate flow

Author: vvgrem@gmail.com

README.md

@@ -44,9 +44,32 @@ The list of supported API versions:
 
 The following auth flows are supported:
 
-- app principals flow: `AuthenticationContext.ctx_auth.acquire_token_for_app(client_id, client_secret)`  (refer [Granting access using SharePoint App-Only](https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs) for a details) 
-- user credentials flow:`AuthenticationContext.ctx_auth.acquire_token_for_user(username, password)`
-- certificate credentials flow `ClientContext.connect_with_certificate(site_url, client_id,thumbprint, certificate_path)`
+- app principals flow: 
+  `ClientContext.with_credentials(client_credentials)`
+  
+  Usage:
+  ``` 
+  client_credentials = ClientCredential('{client_id}'),'{client_secret}')
+  ctx = ClientContext('{url}').with_credentials(client_credentials)
+  ```
+  Documentation: refer [Granting access using SharePoint App-Only](https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azureacs) for a details  
+  
+  Example: [connect_with_app_principal.py](Office365-REST-Python-Client/blob/master/examples/sharepoint/connect_with_app_principal.py)
+  
+- user credentials flow: `ClientContext.with_credentials(user_credentials)`
+
+  Usage:
+  ``` 
+  user_credentials = UserCredential('{username}'),'{password}')
+  ctx = ClientContext('{url}').with_credentials(user_credentials)
+  ```
+  Example: [connect_with_user_credential.py](Office365-REST-Python-Client/blob/master/examples/sharepoint/connect_with_user_credential.py)
+  
+- certificate credentials flow: `ClientContext.with_certificate(tenant, client_id, thumbprint, cert_path)`
+
+  Documentation: [Granting access via Azure AD App-Only](https://docs.microsoft.com/en-us/sharepoint/dev/solution-guidance/security-apponly-azuread)  
+  
+  Example: [connect_with_client_certificate.py](Office365-REST-Python-Client/blob/master/examples/sharepoint/connect_with_client_certificate.py)
 
 #### Examples
  
@@ -95,6 +118,19 @@ print("Web title: {0}".format(web_title))
 ```
 
 
+The list of examples:
+
+- Working with files
+  - [download a file](Office365-REST-Python-Client/blob/master/examples/sharepoint/files/download_file.py) 
+  - [upload a file](Office365-REST-Python-Client/blob/master/examples/sharepoint/files/upload_file.py)
+
+- Working with lists and list items
+  -  [create a list item](Office365-REST-Python-Client/blob/master/examples/sharepoint/lists_and_items/data_generator.py)
+  -  [read a list item](Office365-REST-Python-Client/blob/master/examples/sharepoint/lists_and_items/read_large_list.py)   
+  -  [update a list item](Office365-REST-Python-Client/blob/master/examples/sharepoint/lists_and_items/update_items_batch.py)
+  -  delete a list item 
+  
+
 # Working with Outlook API
 
 The list of supported APIs:
@@ -107,7 +143,7 @@ Since Outlook REST APIs are available in both Microsoft Graph and the Outlook AP
 the following clients are available:
 
 - `GraphClient` which targets Outlook API `v2.0` version (*preferable* nowadays, refer [transition to Microsoft Graph-based Outlook REST API](https://docs.microsoft.com/en-us/outlook/rest/compare-graph-outlook) for a details)   
-- `OutlookClient` which targets Outlook API `v1.0` version (not recommended for usage since `v1.0` version is being deprecated.)
+~~- `OutlookClient` which targets Outlook API `v1.0` version (not recommended for usage since `v1.0` version is being deprecated.)~~
 
 
 #### Authentication

examples/sharepoint/connect_with_client_certificate.py

@@ -0,0 +1,17 @@
+import os
+from office365.sharepoint.client_context import ClientContext
+from settings import settings
+
+cert_settings = {
+    'client_id': '51d03106-4726-442c-86db-70b32fa7547f',
+    'thumbprint': "6B36FBFC86FB1C019EB6496494B9195E6D179DDB",
+    'certificate_path': '{0}/selfsigncert.pem'.format(os.path.dirname(__file__))
+}
+
+
+ctx = ClientContext(settings['url']).with_client_certificate(settings.get('tenant'),
+                                                             cert_settings['client_id'],
+                                                             cert_settings['thumbprint'],
+                                                             cert_settings['certificate_path'])
+current_web = ctx.web.get().execute_query()
+print("{0}".format(current_web.url))

examples/sharepoint/connect_with_user_credential.py

@@ -1,11 +1,9 @@
 from settings import settings
 
-from office365.runtime.auth.user_credential import UserCredential
 from office365.sharepoint.client_context import ClientContext
 
-ctx = ClientContext(settings["url"]).with_credentials(
-                                             UserCredential(settings.get('user_credentials').get('username'),
-                                                            settings.get('user_credentials').get('password')))
+ctx = ClientContext(settings["url"]).with_user_credentials(settings.get('user_credentials').get('username'),
+                                                           settings.get('user_credentials').get('password'))
 
 web = ctx.web.get().execute_query()
 print(web.properties["Url"])

office365/runtime/auth/authentication_context.py

@@ -1,7 +1,11 @@
+import msal
+
 from office365.runtime.auth.client_credential import ClientCredential
 from office365.runtime.auth.providers.acs_token_provider import ACSTokenProvider
+from office365.runtime.auth.providers.ntlm_provider import NtlmProvider
 from office365.runtime.auth.providers.oauth_token_provider import OAuthTokenProvider
 from office365.runtime.auth.providers.saml_token_provider import SamlTokenProvider
+from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.auth.user_credential import UserCredential
 
 
@@ -16,15 +20,44 @@ def __init__(self, url):
         self.url = url
         self._provider = None
 
-    def register_provider(self, credentials_or_token_func):
+    def with_client_certificate(self, tenant, client_id, thumbprint, cert_path):
+        """Creates authenticated SharePoint context via certificate credentials
+
+        :param str tenant: Tenant name, for example {}@
+        :param str cert_path: Path to A PEM encoded certificate private key.
+        :param str thumbprint: Hex encoded thumbprint of the certificate.
+        :param str client_id: The OAuth client id of the calling application.
+        """
+
+        def _acquire_token_for_client_certificate():
+            authority_url = 'https://login.microsoftonline.com/{0}'.format(tenant)
+            scopes = [f"{self.url}/.default"]
+            credentials = {"thumbprint": thumbprint, "private_key": open(cert_path).read()}
+            app = msal.ConfidentialClientApplication(
+                client_id,
+                authority=authority_url,
+                client_credential=credentials,
+            )
+            result = app.acquire_token_for_client(scopes)
+            return TokenResponse.from_json(result)
+
+        self.register_provider(_acquire_token_for_client_certificate)
+        return self
+
+    def register_provider(self, credentials_or_token_func, **kwargs):
         if callable(credentials_or_token_func):
             self._provider = OAuthTokenProvider(credentials_or_token_func)
         elif isinstance(credentials_or_token_func, ClientCredential):
             self._provider = ACSTokenProvider(self.url, credentials_or_token_func.clientId,
                                               credentials_or_token_func.clientSecret)
         elif isinstance(credentials_or_token_func, UserCredential):
-            self._provider = SamlTokenProvider(self.url, credentials_or_token_func.userName,
-                                               credentials_or_token_func.password)
+            allow_ntlm = kwargs.get('allow_ntlm', False)
+            if allow_ntlm:
+                self._provider = NtlmProvider(credentials_or_token_func.userName,
+                                              credentials_or_token_func.password)
+            else:
+                self._provider = SamlTokenProvider(self.url, credentials_or_token_func.userName,
+                                                   credentials_or_token_func.password)
         else:
             raise ValueError("Unknown credential type")
 

office365/sharepoint/client_context.py

@@ -1,5 +1,4 @@
 import copy
-
 from office365.runtime.auth.authentication_context import AuthenticationContext
 from office365.runtime.auth.client_credential import ClientCredential
 from office365.runtime.auth.providers.saml_token_provider import resolve_base_url
@@ -56,14 +55,16 @@ def _init_context_for_web(resp):
         ctx.after_execute(_init_context_for_web)
         return ctx
 
-    def with_client_certificate(self, client_id, thumbprint, cert_path):
+    def with_client_certificate(self, tenant, client_id, thumbprint, cert_path):
         """Creates authenticated SharePoint context via certificate credentials
 
+        :param str tenant: Tenant name
         :param str cert_path: Path to A PEM encoded certificate private key.
         :param str thumbprint: Hex encoded thumbprint of the certificate.
         :param str client_id: The OAuth client id of the calling application.
         """
-        pass
+        self.authentication_context.with_client_certificate(tenant, client_id, thumbprint, cert_path)
+        return self
 
     def with_access_token(self, token_func):
         """
@@ -72,6 +73,17 @@ def with_access_token(self, token_func):
         self.authentication_context.register_provider(token_func)
         return self
 
+    def with_user_credentials(self, username, password, allow_ntlm=False):
+        """
+        Assigns credentials
+
+        :type username: str
+        :type password: str
+        :type allow_ntlm: bool
+        """
+        self.authentication_context.register_provider(UserCredential(username, password), allow_ntlm=allow_ntlm)
+        return self
+
     def with_credentials(self, credentials):
         """
         Assigns credentials

setup.py

@@ -10,18 +10,18 @@
 
 setup(
     name="Office365-REST-Python-Client",
-    version="2.2.3",
+    version="2.3.0",
     author="Vadim Gremyachev",
     author_email="vvgrem@gmail.com",
-    maintainer="Konrad Gądek",
-    maintainer_email="kgadek@gmail.com",
+    maintainer="Konrad Gądek, Domenico Di Nicola",
+    maintainer_email="kgadek@gmail.com, dom.dinicola@gmail.com",
     description="Office 365 Library for Python",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/vgrem/Office365-REST-Python-Client",
     install_requires=['requests', 'msal'],
     extras_require={
-        'NTLMAuthentication': ["requests_ntlm"]
+        'NtlmProvider': ["requests_ntlm"]
     },
     tests_require=['nose', 'adal'],
     test_suite='nose.collector',

tests/onedrive/test_permissions.py

@@ -46,9 +46,9 @@ def test5_get_permission(self):
         self.assertIsNotNone(perm.resource_path)
         self.__class__.target_permission = result[0]
 
-    def test6_update_permission(self):
-        perm_to_update = self.__class__.target_permission
-        perm_to_update.set_property("roles", ["read"]).update().execute_query()
+    # def test6_update_permission(self):
+    #    perm_to_update = self.__class__.target_permission
+    #    perm_to_update.set_property("roles", ["read"]).update().execute_query()
 
     def test7_delete_permission(self):
         perm_to_delete = self.__class__.target_permission