exchangelib.autodiscover.discovery.soap API documentation

# Module `exchangelib.autodiscover.discovery.soap`

Expand source code

    import logging

    from ...configuration import Configuration
    from ...errors import AutoDiscoverFailed, RedirectError, TransportError
    from ...protocol import Protocol
    from ...transport import get_unauthenticated_autodiscover_response
    from ...util import CONNECTION_ERRORS
    from ..cache import autodiscover_cache
    from ..protocol import AutodiscoverProtocol
    from .base import BaseAutodiscovery

    log = logging.getLogger(__name__)

    def discover(email, credentials=None, auth_type=None, retry_policy=None):
        ad_response, protocol = SoapAutodiscovery(email=email, credentials=credentials).discover()
        protocol.config.auth_typ = auth_type
        protocol.config.retry_policy = retry_policy
        return ad_response, protocol

    class SoapAutodiscovery(BaseAutodiscovery):
        URL_PATH = "autodiscover/autodiscover.svc"

        def _build_response(self, ad_response):
            if not ad_response.autodiscover_smtp_address:
                # Autodiscover does not always return an email address. In that case, the requesting email should be used
                ad_response.autodiscover_smtp_address = self.email

            protocol = Protocol(
                config=Configuration(
                    service_endpoint=ad_response.ews_url,
                    credentials=self.credentials,
                    version=ad_response.version,
                    # TODO: Detect EWS service auth type somehow
                )
            )
            return ad_response, protocol

        def _quick(self, protocol):
            try:
                user_response = protocol.get_user_settings(user=self.email)
            except TransportError as e:
                raise AutoDiscoverFailed(f"Response error: {e}")
            return self._step_5(ad=user_response)

        def _get_unauthenticated_response(self, url, method="post"):
            """Get response from server using the given HTTP method

            :param url:
            :return:
            """
            # We are connecting to untrusted servers here, so take necessary precautions.
            self._ensure_valid_hostname(url)

            protocol = AutodiscoverProtocol(
                config=Configuration(
                    service_endpoint=url,
                    retry_policy=self.INITIAL_RETRY_POLICY,
                )
            )
            return None, get_unauthenticated_autodiscover_response(protocol=protocol, method=method)

        def _attempt_response(self, url):
            """Return an (is_valid_response, response) tuple.

            :param url:
            :return:
            """
            self._urls_visited.append(url.lower())
            log.debug("Attempting to get a valid response from %s", url)

            try:
                self._ensure_valid_hostname(url)
            except TransportError:
                return False, None

            protocol = AutodiscoverProtocol(
                config=Configuration(
                    service_endpoint=url,
                    credentials=self.credentials,
                    retry_policy=self.INITIAL_RETRY_POLICY,
                )
            )
            try:
                user_response = protocol.get_user_settings(user=self.email)
            except RedirectError as e:
                if self._redirect_url_is_valid(url=e.url):
                    # The protocol does not specify this explicitly, but by looking at how testconnectivity.microsoft.com
                    # works, it seems that we should follow this URL now and try to get a valid response.
                    return self._attempt_response(url=e.url)
                log.debug("Invalid redirect URL: %s", e.url)
                return False, None
            except TransportError as e:
                log.debug("Failed to get a response: %s", e)
                return False, None
            except CONNECTION_ERRORS as e:
                log.debug("Failed to get a response: %s", e)
                return False, None

            # We got a valid response. Unless this is a URL redirect response, we cache the result
            if not user_response.redirect_url:
                cache_key = self._cache_key
                log.debug("Adding cache entry for key %s: %s", cache_key, protocol.service_endpoint)
                autodiscover_cache[cache_key] = protocol
            return True, user_response

## Functions

`def discover(email, credentials=None, auth_type=None, retry_policy=None)`
  Expand source code

      def discover(email, credentials=None, auth_type=None, retry_policy=None):
          ad_response, protocol = SoapAutodiscovery(email=email, credentials=credentials).discover()
          protocol.config.auth_typ = auth_type
          protocol.config.retry_policy = retry_policy
          return ad_response, protocol

## Classes

`class SoapAutodiscovery (email, credentials=None)`

  Autodiscover is a Microsoft protocol for automatically getting the endpoint of the Exchange server and other connection-related settings holding the email address using only the email address, and username and password of the user.

  For a description of the protocol implemented, see "Autodiscover for Exchange ActiveSync developers":

  https://docs.microsoft.com/en-us/previous-versions/office/developer/exchange-server-interoperability-guidance/hh352638%28v%3dexchg.140%29

  Descriptions of the steps from the article are provided in their respective methods in this class.

  For a description of how to handle autodiscover error messages, see:

  https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/handling-autodiscover-error-messages

  A tip from the article: The client can perform steps 1 through 4 in any order or in parallel to expedite the process, but it must wait for responses to finish at each step before proceeding. Given that many organizations prefer to use the URL in step 2 to set up the Autodiscover service, the client might try this step first.

  Another possibly newer resource which has not yet been attempted is "Outlook 2016 Implementation of Autodiscover": https://support.microsoft.com/en-us/help/3211279/outlook-2016-implementation-of-autodiscover

  WARNING: The autodiscover protocol is very complicated. If you have problems autodiscovering using this implementation, start by doing an official test at https://testconnectivity.microsoft.com

  :param email: The email address to autodiscover :param credentials: Credentials with authorization to make autodiscover lookups for this Account (Default value = None)

  Expand source code

      class SoapAutodiscovery(BaseAutodiscovery):
          URL_PATH = "autodiscover/autodiscover.svc"

          def _build_response(self, ad_response):
              if not ad_response.autodiscover_smtp_address:
                  # Autodiscover does not always return an email address. In that case, the requesting email should be used
                  ad_response.autodiscover_smtp_address = self.email

              protocol = Protocol(
                  config=Configuration(
                      service_endpoint=ad_response.ews_url,
                      credentials=self.credentials,
                      version=ad_response.version,
                      # TODO: Detect EWS service auth type somehow
                  )
              )
              return ad_response, protocol

          def _quick(self, protocol):
              try:
                  user_response = protocol.get_user_settings(user=self.email)
              except TransportError as e:
                  raise AutoDiscoverFailed(f"Response error: {e}")
              return self._step_5(ad=user_response)

          def _get_unauthenticated_response(self, url, method="post"):
              """Get response from server using the given HTTP method

              :param url:
              :return:
              """
              # We are connecting to untrusted servers here, so take necessary precautions.
              self._ensure_valid_hostname(url)

              protocol = AutodiscoverProtocol(
                  config=Configuration(
                      service_endpoint=url,
                      retry_policy=self.INITIAL_RETRY_POLICY,
                  )
              )
              return None, get_unauthenticated_autodiscover_response(protocol=protocol, method=method)

          def _attempt_response(self, url):
              """Return an (is_valid_response, response) tuple.

              :param url:
              :return:
              """
              self._urls_visited.append(url.lower())
              log.debug("Attempting to get a valid response from %s", url)

              try:
                  self._ensure_valid_hostname(url)
              except TransportError:
                  return False, None

              protocol = AutodiscoverProtocol(
                  config=Configuration(
                      service_endpoint=url,
                      credentials=self.credentials,
                      retry_policy=self.INITIAL_RETRY_POLICY,
                  )
              )
              try:
                  user_response = protocol.get_user_settings(user=self.email)
              except RedirectError as e:
                  if self._redirect_url_is_valid(url=e.url):
                      # The protocol does not specify this explicitly, but by looking at how testconnectivity.microsoft.com
                      # works, it seems that we should follow this URL now and try to get a valid response.
                      return self._attempt_response(url=e.url)
                  log.debug("Invalid redirect URL: %s", e.url)
                  return False, None
              except TransportError as e:
                  log.debug("Failed to get a response: %s", e)
                  return False, None
              except CONNECTION_ERRORS as e:
                  log.debug("Failed to get a response: %s", e)
                  return False, None

              # We got a valid response. Unless this is a URL redirect response, we cache the result
              if not user_response.redirect_url:
                  cache_key = self._cache_key
                  log.debug("Adding cache entry for key %s: %s", cache_key, protocol.service_endpoint)
                  autodiscover_cache[cache_key] = protocol
              return True, user_response

  ### Ancestors

  - BaseAutodiscovery

  ### Class variables

  `var URL_PATH`