Office365-REST-Python-Client 2.5.14__py3-none-any.whl → 2.6.1__py3-none-any.whl

office365/runtime/auth/entra/authentication_context.py

@@ -0,0 +1,165 @@
+from typing import Optional
+
+from office365.azure_env import AzureEnvironment
+from office365.runtime.auth.token_response import TokenResponse
+
+
+class AuthenticationContext(object):
+    """Provides authentication context for Microsoft Graph client"""
+
+    def __init__(
+        self,
+        tenant=None,
+        scopes=None,
+        token_cache=None,
+        environment=AzureEnvironment.Global,
+    ):
+        """
+        :param str tenant: Tenant name, for example: contoso.onmicrosoft.com
+        :param list[str] or None scopes: Scopes requested to access an API
+        :param Any token_cache: Default cache is in memory only,
+            Refer https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
+        """
+        self._tenant = tenant
+        if scopes is None:
+            scopes = [
+                "{0}/.default".format(AzureEnvironment.get_graph_authority(environment))
+            ]
+        self._scopes = scopes
+        self._token_cache = token_cache
+        self._token_callback = None
+        self._environment = environment
+
+    def acquire_token(self):
+        # type: () -> TokenResponse
+        """Acquire access token"""
+        if not self._token_callback:
+            raise ValueError("Token callback is not set.")
+        token_resp = self._token_callback()
+        token = TokenResponse.from_json(token_resp)
+        return token
+
+    def with_access_token(self, token_callback):
+        """"""
+        self._token_callback = token_callback
+        return self
+
+    def with_certificate(self, client_id, thumbprint, private_key):
+        """
+        Initializes the confidential client with client certificate
+
+        :param str client_id: The OAuth client id of the calling application.
+        :param str thumbprint: Thumbprint
+        :param str private_key: Private key
+        """
+        import msal
+
+        app = msal.ConfidentialClientApplication(
+            client_id,
+            authority=self.authority_url,
+            client_credential={
+                "thumbprint": thumbprint,
+                "private_key": private_key,
+            },
+            token_cache=self._token_cache,  # Default cache is in memory only.
+            # You can learn how to use SerializableTokenCache from
+            # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
+        )
+
+        def _acquire_token():
+            return app.acquire_token_for_client(scopes=self._scopes)
+
+        return self.with_access_token(_acquire_token)
+
+    def with_client_secret(self, client_id, client_secret):
+        # type: (str, str) -> "AuthenticationContext"
+        """
+        Initializes the confidential client with client secret
+
+        :param str client_id: The OAuth client id of the calling application.
+        :param str client_secret: Client secret
+        """
+        import msal
+
+        app = msal.ConfidentialClientApplication(
+            client_id,
+            authority=self.authority_url,
+            client_credential=client_secret,
+            token_cache=self._token_cache,
+        )
+
+        def _acquire_token():
+            return app.acquire_token_for_client(scopes=self._scopes)
+
+        return self.with_access_token(_acquire_token)
+
+    def with_token_interactive(self, client_id, username=None):
+        # type: (str, Optional[str]) -> "AuthenticationContext"
+        """
+        Initializes the client via user credentials
+        Note: only works if your app is registered with redirect_uri as http://localhost
+
+        :param str client_id: The OAuth client id of the calling application.
+        :param str username: Typically a UPN in the form of an email address.
+        """
+        import msal
+
+        app = msal.PublicClientApplication(client_id, authority=self.authority_url)
+
+        def _acquire_token():
+            # The pattern to acquire a token looks like this.
+            result = None
+
+            # Firstly, check the cache to see if this end user has signed in before
+            accounts = app.get_accounts(username=username)
+            if accounts:
+                chosen = accounts[0]  # Assuming the end user chose this one to proceed
+                # Now let's try to find a token in cache for this account
+                result = app.acquire_token_silent(self._scopes, account=chosen)
+
+            if not result:
+                result = app.acquire_token_interactive(
+                    self._scopes,
+                    login_hint=username,
+                )
+            return result
+
+        return self.with_access_token(_acquire_token)
+
+    def with_username_and_password(self, client_id, username, password):
+        # type: (str, str, str) -> "AuthenticationContext"
+        """
+        Initializes the client via user credentials
+
+        :param str client_id: The OAuth client id of the calling application.
+        :param str username: Typically a UPN in the form of an email address.
+        :param str password: The password.
+        """
+        import msal
+
+        app = msal.PublicClientApplication(
+            authority=self.authority_url,
+            client_id=client_id,
+        )
+
+        def _acquire_token():
+            result = None
+            accounts = app.get_accounts(username=username)
+            if accounts:
+                result = app.acquire_token_silent(self._scopes, account=accounts[0])
+
+            if not result:
+                result = app.acquire_token_by_username_password(
+                    username=username,
+                    password=password,
+                    scopes=self._scopes,
+                )
+            return result
+
+        return self.with_access_token(_acquire_token)
+
+    @property
+    def authority_url(self):
+        return "{0}/{1}".format(
+            AzureEnvironment.get_login_authority(self._environment), self._tenant
+        )

office365/runtime/auth/providers/acs_token_provider.py

@@ -3,6 +3,7 @@ from typing import Optional
 import requests
 
 import office365.logger
+from office365.azure_env import AzureEnvironment
 from office365.runtime.auth.authentication_provider import AuthenticationProvider
 from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.compat import urlparse
@@ -10,7 +11,7 @@ from office365.runtime.http.request_options import RequestOptions
 
 
 class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
-    def __init__(self, url, client_id, client_secret, environment="commercial"):
+    def __init__(self, url, client_id, client_secret, environment=None):
         """
         Provider to acquire the access token from a Microsoft Azure Access Control Service (ACS)
 
@@ -18,7 +19,7 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         :param str client_secret: Secret string that the application uses to prove its identity when requesting a token
         :param str url: SharePoint web or site url
         :param str environment: The Office 365 Cloud Environment endpoint used for authentication
-            defaults to 'commercial'.
+            defaults to 'Azure Global'.
         """
         self.url = url
         self.redirect_url = None
@@ -26,18 +27,14 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         self.SharePointPrincipal = "00000003-0000-0ff1-ce00-000000000000"
         self._client_id = client_id
         self._client_secret = client_secret
-        self._cached_token = None
+        self._cached_token = None  # type: Optional[TokenResponse]
         self._environment = environment
 
     def authenticate_request(self, request):
         # type: (RequestOptions) -> None
-        self.ensure_app_only_access_token()
-        request.set_header("Authorization", self._get_authorization_header())
-
-    def ensure_app_only_access_token(self):
         if self._cached_token is None:
             self._cached_token = self.get_app_only_access_token()
-        return self._cached_token and self._cached_token.is_valid
+        request.set_header("Authorization", self._cached_token.authorization_header)
 
     def get_app_only_access_token(self):
         """Retrieves an app-only access token from ACS"""
@@ -65,9 +62,7 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             self.SharePointPrincipal, target_host, target_realm
         )
         principal_id = self.get_formatted_principal(self._client_id, None, target_realm)
-        sts_url = self.get_security_token_service_url(
-            target_realm, environment=self._environment
-        )
+        sts_url = self.get_security_token_service_url(target_realm)
         oauth2_request = {
             "grant_type": "client_credentials",
             "client_id": principal_id,
@@ -86,11 +81,6 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
     def _get_realm_from_target_url(self):
         """Get the realm for the URL"""
         response = requests.head(url=self.url, headers={"Authorization": "Bearer"})
-        return self.process_realm_response(response)
-
-    @staticmethod
-    def process_realm_response(response):
-        # type: (requests.Response) -> Optional[str]
         header_key = "WWW-Authenticate"
         if header_key in response.headers:
             auth_values = response.headers[header_key].split(",")
@@ -105,20 +95,15 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             return "{0}/{1}@{2}".format(principal_name, host_name, realm)
         return "{0}@{1}".format(principal_name, realm)
 
-    @staticmethod
-    def get_security_token_service_url(realm, environment):
-        # type: (str, str) -> str
-        if environment == "GCCH":
-            return "https://login.microsoftonline.us/{0}/tokens/OAuth/2".format(realm)
+    def get_security_token_service_url(self, realm):
+        # type: (str) -> str
+        if self._environment:
+            return "{0}/{1}/tokens/OAuth/2".format(
+                AzureEnvironment.get_login_authority(self._environment), realm
+            )
         else:
             return (
                 "https://accounts.accesscontrol.windows.net/{0}/tokens/OAuth/2".format(
                     realm
                 )
             )
-
-    def _get_authorization_header(self):
-        return "Bearer {0}".format(self._cached_token.accessToken)
-
-    def get_last_error(self):
-        return self.error

office365/runtime/auth/providers/saml_token_provider.py

@@ -1,5 +1,7 @@
 import os
 import uuid
+from datetime import datetime, timezone
+from typing import Optional
 from xml.dom import minidom
 from xml.etree import ElementTree
 
@@ -7,6 +9,7 @@ import requests
 import requests.utils
 
 import office365.logger
+from office365.runtime.auth.auth_cookies import AuthCookies
 from office365.runtime.auth.authentication_provider import AuthenticationProvider
 from office365.runtime.auth.sts_profile import STSProfile
 from office365.runtime.auth.user_realm_info import UserRealmInfo
@@ -14,33 +17,21 @@ from office365.runtime.auth.user_realm_info import UserRealmInfo
 office365.logger.ensure_debug_secrets()
 
 
-def resolve_base_url(url):
-    parts = url.split("://")
-    host_name = parts[1].split("/")[0]
-    return parts[0] + "://" + host_name
+def string_escape(value):
+    value = value.replace("&", "&")
+    value = value.replace("<", "&lt;")
+    value = value.replace(">", "&gt;")
+    value = value.replace('"', "&quot;")
+    value = value.replace("'", "&apos;")
+    return value
 
 
-def xml_escape(s_val):
-    s_val = s_val.replace("&", "&amp;")
-    s_val = s_val.replace("<", "&lt;")
-    s_val = s_val.replace(">", "&gt;")
-    s_val = s_val.replace('"', "&quot;")
-    s_val = s_val.replace("'", "&apos;")
-    return s_val
-
-
-def is_valid_auth_cookies(values):
-    """
-    Validates authorization cookies
-    """
-    return any(values) and (
-        values.get("FedAuth", None) is not None
-        or values.get("SPOIDCRL", None) is not None
-    )
+def datetime_escape(value):
+    return value.isoformat("T")[:-9] + "Z"
 
 
 class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
-    def __init__(self, url, username, password, browser_mode, environment="commercial"):
+    def __init__(self, url, username, password, browser_mode, environment=None):
         """
         SAML Security Token Service provider (claims-based authentication)
 
@@ -49,18 +40,16 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         :param str password: The password
         :param bool browser_mode:
         :param str environment: The Office 365 Cloud Environment endpoint used for authentication.
-        By default, this will be set to commercial ('commercial', 'GCCH')
         """
         # Security Token Service info
-        self._sts_profile = STSProfile(resolve_base_url(url), environment)
+        self._sts_profile = STSProfile(url, environment)
         # Obtain authentication cookies, using the browser mode
         self._browser_mode = browser_mode
-        self._environment = environment
         # Last occurred error
         self.error = ""
         self._username = username
         self._password = password
-        self._cached_auth_cookies = None
+        self._cached_auth_cookies = None  # type: Optional[AuthCookies]
         self.__ns_prefixes = {
             "S": "{http://www.w3.org/2003/05/soap-envelope}",
             "s": "{http://www.w3.org/2003/05/soap-envelope}",
@@ -82,24 +71,20 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         Authenticate request handler
         """
         logger = self.logger(self.authenticate_request.__name__)
-        self.ensure_authentication_cookie()
-        logger.debug_secrets(self._cached_auth_cookies)
-        cookie_header_value = "; ".join(
-            [
-                "=".join([key, str(val)])
-                for key, val in self._cached_auth_cookies.items()
-            ]
-        )
-        request.set_header("Cookie", cookie_header_value)
 
-    def ensure_authentication_cookie(self):
-        if self._cached_auth_cookies is None:
+        request_time = datetime.now(timezone.utc)
+        if (
+            self._cached_auth_cookies is None
+            or request_time >= self._sts_profile.expires
+        ):
+            self._sts_profile.reset()
             self._cached_auth_cookies = self.get_authentication_cookie()
-        return True
+        logger.debug_secrets(self._cached_auth_cookies)
+        request.set_header("Cookie", self._cached_auth_cookies.cookie_header)
 
     def get_authentication_cookie(self):
         """Acquire authentication cookie"""
-        logger = self.logger(self.ensure_authentication_cookie.__name__)
+        logger = self.logger(self.get_authentication_cookie.__name__)
         logger.debug("get_authentication_cookie called")
 
         try:
@@ -132,9 +117,6 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             return info
         return None
 
-    def get_last_error(self):
-        return self.error
-
     def _acquire_service_token_from_adfs(self, adfs_url):
         logger = self.logger(self._acquire_service_token_from_adfs.__name__)
 
@@ -143,11 +125,11 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             {
                 "auth_url": adfs_url,
                 "message_id": str(uuid.uuid4()),
-                "username": xml_escape(self._username),
-                "password": xml_escape(self._password),
-                "created": self._sts_profile.created,
-                "expires": self._sts_profile.expires,
-                "issuer": self._sts_profile.tokenIssuer,
+                "username": string_escape(self._username),
+                "password": string_escape(self._password),
+                "created": datetime_escape(self._sts_profile.created),
+                "expires": datetime_escape(self._sts_profile.expires),
+                "issuer": self._sts_profile.token_issuer,
             },
         )
 
@@ -194,13 +176,13 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         payload = self._prepare_request_from_template(
             "SAML.xml",
             {
-                "auth_url": self._sts_profile.authorityUrl,
-                "username": xml_escape(self._username),
-                "password": xml_escape(self._password),
+                "auth_url": self._sts_profile.site_url,
+                "username": string_escape(self._username),
+                "password": string_escape(self._password),
                 "message_id": str(uuid.uuid4()),
-                "created": self._sts_profile.created,
-                "expires": self._sts_profile.expires,
-                "issuer": self._sts_profile.tokenIssuer,
+                "created": datetime_escape(self._sts_profile.created),
+                "expires": datetime_escape(self._sts_profile.expires),
+                "issuer": self._sts_profile.token_issuer,
             },
         )
         logger.debug_secrets("options: %s", payload)
@@ -300,9 +282,9 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
                 },
             )
         logger.debug_secrets("session.cookies: %s", session.cookies)
-        cookies = requests.utils.dict_from_cookiejar(session.cookies)
+        cookies = AuthCookies(requests.utils.dict_from_cookiejar(session.cookies))
         logger.debug_secrets("cookies: %s", cookies)
-        if not is_valid_auth_cookies(cookies):
+        if not cookies.is_valid:
             self.error = (
                 "An error occurred while retrieving auth cookies from {0}".format(
                     self._sts_profile.signin_page_url
@@ -312,19 +294,16 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             raise ValueError(self.error)
         return cookies
 
-    @staticmethod
-    def _prepare_request_from_template(template_name, params):
+    def _prepare_request_from_template(self, template_name, params):
         """Construct the request body to acquire security token from STS endpoint"""
-        logger = SamlTokenProvider.logger()
+        logger = self.logger(self._prepare_request_from_template.__name__)
         logger.debug_secrets("params: %s", params)
-        f = open(
-            os.path.join(os.path.dirname(__file__), "templates", template_name),
-            encoding="utf8",
+
+        template_path = os.path.join(
+            os.path.dirname(__file__), "templates", template_name
         )
-        try:
+
+        with open(template_path, encoding="utf8") as f:
             data = f.read()
-            for key in params:
-                data = data.replace("{" + key + "}", str(params[key]))
-            return data
-        finally:
-            f.close()
+
+        return data.format(**params)

office365/runtime/auth/sts_profile.py

@@ -1,40 +1,55 @@
 from datetime import datetime, timedelta
 
+from office365.azure_env import AzureEnvironment
 from office365.runtime.compat import timezone, urlparse
 
 
 class STSProfile(object):
-    def __init__(self, authority_url, environment):
-        """
-        :type authority_url: str
-        """
-        self.authorityUrl = authority_url
-        if environment == "GCCH":
-            self.serviceUrl = "https://login.microsoftonline.us"
-        else:
-            self.serviceUrl = "https://login.microsoftonline.com"
-        self.securityTokenServicePath = "extSTS.srf"
-        self.userRealmServicePath = "GetUserRealm.srf"
-        self.tokenIssuer = "urn:federation:MicrosoftOnline"
-        now = datetime.now(tz=timezone.utc)
-        self.created = now.astimezone(timezone.utc).isoformat("T")[:-9] + "Z"
-        self.expires = (now + timedelta(minutes=10)).astimezone(timezone.utc).isoformat(
-            "T"
-        )[:-9] + "Z"
-        self.signInPage = "_forms/default.aspx?wa=wsignin1.0"
+    def __init__(self, site_url, environment=None):
+        # type: (str, str) -> None
+        self._site_url = site_url
+        self._environment = environment
+        self._created = datetime.now(tz=timezone.utc)
+        self._expires = self._created + timedelta(minutes=30)
+
+    def reset(self):
+        """Renew the expiration time."""
+        self._created = datetime.now(tz=timezone.utc)
+        self._expires = self._created + timedelta(minutes=30)
 
     @property
     def tenant(self):
-        return urlparse(self.authorityUrl).netloc
+        return urlparse(self._site_url).netloc
 
     @property
     def security_token_service_url(self):
-        return "/".join([self.serviceUrl, self.securityTokenServicePath])
+        return "{0}/extSTS.srf".format(
+            AzureEnvironment.get_login_authority(self._environment),
+        )
 
     @property
     def signin_page_url(self):
-        return "/".join([self.authorityUrl, self.signInPage])
+        site_info = urlparse(self._site_url)
+        return "{0}://{1}/_forms/default.aspx?wa=wsignin1.0".format(site_info.scheme, site_info.netloc)
 
     @property
     def user_realm_service_url(self):
-        return "/".join([self.serviceUrl, self.userRealmServicePath])
+        return "{0}/GetUserRealm.srf".format(
+            AzureEnvironment.get_login_authority(self._environment),
+        )
+
+    @property
+    def token_issuer(self):
+        return "urn:federation:MicrosoftOnline"
+
+    @property
+    def created(self):
+        return self._created
+
+    @property
+    def expires(self):
+        return self._expires
+
+    @property
+    def site_url(self):
+        return self._site_url

office365/runtime/auth/token_response.py

@@ -9,6 +9,10 @@ class TokenResponse(object):
     def is_valid(self):
         return self.accessToken is not None and self.tokenType == "Bearer"
 
+    @property
+    def authorization_header(self):
+        return "Bearer {0}".format(self.accessToken)
+
     @staticmethod
     def from_json(value):
         error = value.get("error", None)

office365/sharepoint/administration/custom_fonts_resource.py

@@ -0,0 +1,5 @@
+from office365.runtime.client_value import ClientValue
+
+
+class CustomFontsResource(ClientValue):
+    """ """

office365/sharepoint/administration/sitemove/service.py

@@ -0,0 +1,68 @@
+from typing import TYPE_CHECKING
+
+from office365.runtime.client_result import ClientResult
+from office365.runtime.client_value import ClientValue
+from office365.runtime.paths.service_operation import ServiceOperationPath
+from office365.runtime.queries.service_operation import ServiceOperationQuery
+from office365.sharepoint.entity import Entity
+
+if TYPE_CHECKING:
+    from office365.sharepoint.client_context import ClientContext
+
+
+class SystemSiteLockExpirationResult(ClientValue):
+    """"""
+
+    def __init__(self, error=None, expiration=None):
+        self.Error = error
+        self.Expiration = expiration
+
+
+class SiteMoveService(Entity):
+    """ """
+
+    def __init__(
+        self,
+        context,
+        site_id,
+        site_subscription_id=None,
+        source_database_id=None,
+        target_database_id=None,
+    ):
+        # type: (ClientContext, str, str, str, str) -> None
+        """"""
+        static_path = ServiceOperationPath(
+            "Microsoft.SharePoint.Administration.SiteMove.Service.SiteMoveService",
+            {
+                "siteId": site_id,
+                "siteSubscriptionId": site_subscription_id,
+                "sourceDatabaseId": source_database_id,
+                "targetDatabaseId": target_database_id,
+            },
+        )
+        super(SiteMoveService, self).__init__(context, static_path)
+
+    def acquire_system_site_lock(
+        self, lock_requestor, lock_type, lease_duration_in_minutes
+    ):
+        """"""
+        return_type = ClientResult(self.context, SystemSiteLockExpirationResult())
+        payload = {
+            "lockRequestor": lock_requestor,
+            "lockType": lock_type,
+            "leaseDurationInMinutes": lease_duration_in_minutes,
+        }
+        qry = ServiceOperationQuery(
+            self,
+            "AcquireSystemSiteLock",
+            None,
+            payload,
+            None,
+            return_type,
+        )
+        self.context.add_query(qry)
+        return return_type
+
+    @property
+    def entity_type_name(self):
+        return "Microsoft.SharePoint.Administration.SiteMove.Service.SiteMoveService"

office365/sharepoint/administration/sitemove/service_info.py

@@ -0,0 +1,11 @@
+from office365.runtime.client_value import ClientValue
+
+
+class SiteMoveServiceInfo(ClientValue):
+    """ """
+
+    @property
+    def entity_type_name(self):
+        return (
+            "Microsoft.SharePoint.Administration.SiteMove.Service.SiteMoveServiceInfo"
+        )

office365/sharepoint/changes/item.py

@@ -20,6 +20,21 @@ class ChangeItem(Change):
         """Specifies an identifier for the content type"""
         return self.properties.get("ContentTypeId", ContentTypeId())
 
+    @property
+    def editor(self):
+        """Specifies the editor of the changed item."""
+        return self.properties.get("Editor", None)
+
+    @property
+    def editor_email_hint(self):
+        """Returns the email corresponding to Editor."""
+        return self.properties.get("EditorEmailHint", None)
+
+    @property
+    def editor_login_name(self):
+        """Returns login name of the Editor."""
+        return self.properties.get("EditorLoginName", None)
+
     @property
     def file_type(self):
         # type: () -> Optional[str]