exchangelib.autodiscover API documentation

# Module `exchangelib.autodiscover`

Expand source code

    from .cache import AutodiscoverCache, autodiscover_cache
    from .discovery.pox import PoxAutodiscovery as Autodiscovery
    from .discovery.pox import discover
    from .protocol import AutodiscoverProtocol

    def close_connections():
        with autodiscover_cache:
            autodiscover_cache.close()

    def clear_cache():
        with autodiscover_cache:
            autodiscover_cache.clear()

    __all__ = [
        "AutodiscoverCache",
        "AutodiscoverProtocol",
        "Autodiscovery",
        "discover",
        "autodiscover_cache",
        "close_connections",
        "clear_cache",
    ]

## Sub-modules

`exchangelib.autodiscover.cache`
`exchangelib.autodiscover.discovery`
`exchangelib.autodiscover.properties`
`exchangelib.autodiscover.protocol`

## Functions

`def clear_cache()`
  Expand source code

      def clear_cache():
          with autodiscover_cache:
              autodiscover_cache.clear()

`def close_connections()`
  Expand source code

      def close_connections():
          with autodiscover_cache:
              autodiscover_cache.close()

`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 = PoxAutodiscovery(email=email, credentials=credentials).discover()
          protocol.config.auth_typ = auth_type
          protocol.config.retry_policy = retry_policy
          return ad_response, protocol

## Classes

`class AutodiscoverCache`

  Stores the translation from (email domain, credentials) -> AutodiscoverProtocol object, so we can re-use TCP connections to an autodiscover server within the same process. Also persists the email domain -> (autodiscover endpoint URL, auth_type) translation to the filesystem so the cache can be shared between multiple processes.

  According to Microsoft, we may forever cache the (email domain -> autodiscover endpoint URL) mapping, or until it stops responding. My previous experience with Exchange products in mind, I'm not sure if I should trust that advice. But it could save some valuable seconds every time we start a new connection to a known server. In any case, the persistent storage must not contain any sensitive information since the cache could be readable by unprivileged users. Domain, endpoint and auth_type are OK to cache since this info is make publicly available on HTTP and DNS servers via the autodiscover protocol. Just don't persist any credential info.

  If an autodiscover lookup fails for any reason, the corresponding cache entry must be purged.

  'shelve' is supposedly thread-safe and process-safe, which suits our needs.

  Expand source code

      class AutodiscoverCache:
          """Stores the translation from (email domain, credentials) -> AutodiscoverProtocol object, so we can re-use TCP
          connections to an autodiscover server within the same process. Also persists the email domain -> (autodiscover
          endpoint URL, auth_type) translation to the filesystem so the cache can be shared between multiple processes.

          According to Microsoft, we may forever cache the (email domain -> autodiscover endpoint URL) mapping, or until
          it stops responding. My previous experience with Exchange products in mind, I'm not sure if I should trust that
          advice. But it could save some valuable seconds every time we start a new connection to a known server. In any
          case, the persistent storage must not contain any sensitive information since the cache could be readable by
          unprivileged users. Domain, endpoint and auth_type are OK to cache since this info is make publicly available on
          HTTP and DNS servers via the autodiscover protocol. Just don't persist any credential info.

          If an autodiscover lookup fails for any reason, the corresponding cache entry must be purged.

          'shelve' is supposedly thread-safe and process-safe, which suits our needs.
          """

          def __init__(self):
              self._protocols = {}  # Mapping from (domain, credentials) to AutodiscoverProtocol
              self._lock = RLock()

          @property
          def _storage_file(self):
              return AUTODISCOVER_PERSISTENT_STORAGE

          def clear(self):
              # Wipe the entire cache
              with shelve_open_with_failover(self._storage_file) as db:
                  db.clear()
              self._protocols.clear()

          def __len__(self):
              return len(self._protocols)

          def __contains__(self, key):
              domain = key[0]
              with shelve_open_with_failover(self._storage_file) as db:
                  return str(domain) in db

          def __getitem__(self, key):
              protocol = self._protocols.get(key)
              if protocol:
                  return protocol
              domain, credentials = key
              with shelve_open_with_failover(self._storage_file) as db:
                  endpoint, auth_type, retry_policy = db[str(domain)]  # It's OK to fail with KeyError here
              protocol = AutodiscoverProtocol(
                  config=Configuration(
                      service_endpoint=endpoint, credentials=credentials, auth_type=auth_type, retry_policy=retry_policy
                  )
              )
              self._protocols[key] = protocol
              return protocol

          def __setitem__(self, key, protocol):
              # Populate both local and persistent cache
              domain = key[0]
              with shelve_open_with_failover(self._storage_file) as db:
                  # Don't change this payload without bumping the cache file version in shelve_filename()
                  db[str(domain)] = (protocol.service_endpoint, protocol.auth_type, protocol.retry_policy)
              self._protocols[key] = protocol

          def __delitem__(self, key):
              # Empty both local and persistent cache. Don't fail on non-existing entries because we could end here
              # multiple times due to race conditions.
              domain = key[0]
              with shelve_open_with_failover(self._storage_file) as db:
                  with suppress(KeyError):
                      del db[str(domain)]
              with suppress(KeyError):
                  del self._protocols[key]

          def close(self):
              # Close all open connections
              for (domain, _), protocol in self._protocols.items():
                  log.debug("Domain %s: Closing sessions", domain)
                  protocol.close()
                  del protocol
              self._protocols.clear()

          def __enter__(self):
              self._lock.__enter__()

          def __exit__(self, *args, **kwargs):
              self._lock.__exit__(*args, **kwargs)

          def __del__(self):
              # pylint: disable=bare-except
              try:
                  self.close()
              except Exception:  # nosec
                  # __del__ should never fail
                  pass

          def __str__(self):
              return str(self._protocols)

  ### Methods

  `def clear(self)`
    Expand source code

        def clear(self):
            # Wipe the entire cache
            with shelve_open_with_failover(self._storage_file) as db:
                db.clear()
            self._protocols.clear()

  `def close(self)`
    Expand source code

        def close(self):
            # Close all open connections
            for (domain, _), protocol in self._protocols.items():
                log.debug("Domain %s: Closing sessions", domain)
                protocol.close()
                del protocol
            self._protocols.clear()

`class AutodiscoverProtocol (config)`

  Protocol which implements the bare essentials for autodiscover.

  Expand source code

      class AutodiscoverProtocol(BaseProtocol):
          """Protocol which implements the bare essentials for autodiscover."""

          TIMEOUT = 10  # Seconds

          def __init__(self, config):
              if not config.version:
                  # Default to the latest supported version
                  config.version = Version.all_versions()[0]
              super().__init__(config=config)

          def __str__(self):
              return f"""\
      Autodiscover endpoint: {self.service_endpoint}
      Auth type: {self.auth_type}"""

          @property
          def version(self):
              return self.config.version

          @property
          def auth_type(self):
              # Autodetect authentication type if necessary
              if self.config.auth_type is None:
                  self.config.auth_type = self.get_auth_type()
              return self.config.auth_type

          def get_auth_type(self):
              # Autodetect authentication type.
              return get_autodiscover_authtype(protocol=self)

          def get_user_settings(self, user):
              return GetUserSettings(protocol=self).get(
                  users=[user],
                  settings=[
                      "user_dn",
                      "mailbox_dn",
                      "user_display_name",
                      "auto_discover_smtp_address",
                      "external_ews_url",
                      "ews_supported_schemas",
                  ],
              )

          def dummy_xml(self):
              # Generate a valid EWS request for SOAP autodiscovery
              svc = GetUserSettings(protocol=self)
              return svc.wrap(
                  content=svc.get_payload(
                      users=["DUMMY@example.com"],
                      settings=["auto_discover_smtp_address"],
                  ),
                  api_version=self.config.version.api_version,
              )

  ### Ancestors

  - BaseProtocol

  ### Class variables

  `var TIMEOUT`

  ### Instance variables

  `var auth_type`
    Expand source code

        @property
        def auth_type(self):
            # Autodetect authentication type if necessary
            if self.config.auth_type is None:
                self.config.auth_type = self.get_auth_type()
            return self.config.auth_type

  `var version`
    Expand source code

        @property
        def version(self):
            return self.config.version

  ### Methods

  `def dummy_xml(self)`
    Expand source code

        def dummy_xml(self):
            # Generate a valid EWS request for SOAP autodiscovery
            svc = GetUserSettings(protocol=self)
            return svc.wrap(
                content=svc.get_payload(
                    users=["DUMMY@example.com"],
                    settings=["auto_discover_smtp_address"],
                ),
                api_version=self.config.version.api_version,
            )

  `def get_user_settings(self, user)`
    Expand source code

        def get_user_settings(self, user):
            return GetUserSettings(protocol=self).get(
                users=[user],
                settings=[
                    "user_dn",
                    "mailbox_dn",
                    "user_display_name",
                    "auto_discover_smtp_address",
                    "external_ews_url",
                    "ews_supported_schemas",
                ],
            )

  ### Inherited members

  - `BaseProtocol`:
    - `HTTP_ADAPTER_CLS`
    - `decrease_poolsize`
    - `get_auth_type`
    - `increase_poolsize`
`class Autodiscovery (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 PoxAutodiscovery(BaseAutodiscovery):
          URL_PATH = "Autodiscover/Autodiscover.xml"

          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.user.autodiscover_smtp_address = self.email

              protocol = Protocol(
                  config=Configuration(
                      service_endpoint=ad_response.protocol.ews_url,
                      credentials=self.credentials,
                      version=ad_response.version,
                      auth_type=ad_response.protocol.auth_type,
                  )
              )
              return ad_response, protocol

          def _quick(self, protocol):
              try:
                  r = self._get_authenticated_response(protocol=protocol)
              except TransportError as e:
                  raise AutoDiscoverFailed(f"Response error: {e}")
              if r.status_code == 200:
                  try:
                      ad = Autodiscover.from_bytes(bytes_content=r.content)
                  except ParseError as e:
                      raise AutoDiscoverFailed(f"Invalid response: {e}")
                  else:
                      return self._step_5(ad=ad)
              raise AutoDiscoverFailed(f"Invalid response code: {r.status_code}")

          def _get_unauthenticated_response(self, url, method="post"):
              """Get auth type by tasting headers from the server. Do POST requests be default. HEAD is too error-prone, and
              some servers are set up to redirect to OWA on all requests except POST to the autodiscover endpoint.

              :param url:
              :param method:  (Default value = 'post')
              :return:
              """
              # We are connecting to untrusted servers here, so take necessary precautions.
              self._ensure_valid_hostname(url)

              kwargs = dict(
                  url=url, headers=DEFAULT_HEADERS.copy(), allow_redirects=False, timeout=AutodiscoverProtocol.TIMEOUT
              )
              if method == "post":
                  kwargs["data"] = Autodiscover.payload(email=self.email)
              retry = 0
              t_start = time.monotonic()
              while True:
                  _back_off_if_needed(self.INITIAL_RETRY_POLICY.back_off_until)
                  log.debug("Trying to get response from %s", url)
                  with AutodiscoverProtocol.raw_session(url) as s:
                      try:
                          r = getattr(s, method)(**kwargs)
                          r.close()  # Release memory
                          break
                      except TLS_ERRORS as e:
                          # Don't retry on TLS errors. They will most likely be persistent.
                          raise TransportError(str(e))
                      except CONNECTION_ERRORS as e:
                          r = DummyResponse(url=url, request_headers=kwargs["headers"])
                          total_wait = time.monotonic() - t_start
                          if self.INITIAL_RETRY_POLICY.may_retry_on_error(response=r, wait=total_wait):
                              log.debug("Connection error on URL %s (retry %s, error: %s). Cool down", url, retry, e)
                              # Don't respect the 'Retry-After' header. We don't know if this is a useful endpoint, and we
                              # want autodiscover to be reasonably fast.
                              self.INITIAL_RETRY_POLICY.back_off(self.RETRY_WAIT)
                              retry += 1
                              continue
                          log.debug("Connection error on URL %s: %s", url, e)
                          raise TransportError(str(e))
              try:
                  auth_type = get_auth_method_from_response(response=r)
              except UnauthorizedError:
                  # Failed to guess the auth type
                  auth_type = NOAUTH
              if r.status_code in (301, 302) and "location" in r.headers:
                  # Make the redirect URL absolute
                  try:
                      r.headers["location"] = get_redirect_url(r)
                  except TransportError:
                      del r.headers["location"]
              return auth_type, r

          def _get_authenticated_response(self, protocol):
              """Get a response by using the credentials provided. We guess the auth type along the way.

              :param protocol:
              :return:
              """
              # Redo the request with the correct auth
              data = Autodiscover.payload(email=self.email)
              headers = DEFAULT_HEADERS.copy()
              session = protocol.get_session()
              if GSSAPI in AUTH_TYPE_MAP and isinstance(session.auth, AUTH_TYPE_MAP[GSSAPI]):
                  # https://docs.microsoft.com/en-us/exchange/client-developer/web-service-reference/pox-autodiscover-request-for-exchange
                  headers["X-ClientCanHandle"] = "Negotiate"
              try:
                  r, session = post_ratelimited(
                      protocol=protocol,
                      session=session,
                      url=protocol.service_endpoint,
                      headers=headers,
                      data=data,
                  )
                  protocol.release_session(session)
              except UnauthorizedError as e:
                  # It's entirely possible for the endpoint to ask for login. We should continue if login fails because this
                  # isn't necessarily the right endpoint to use.
                  raise TransportError(str(e))
              except RedirectError as e:
                  r = DummyResponse(url=protocol.service_endpoint, headers={"location": e.url}, status_code=302)
              return r

          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:
                  auth_type, r = self._get_unauthenticated_response(url=url)
                  ad_protocol = AutodiscoverProtocol(
                      config=Configuration(
                          service_endpoint=url,
                          credentials=self.credentials,
                          auth_type=auth_type,
                          retry_policy=self.INITIAL_RETRY_POLICY,
                      )
                  )
                  if auth_type != NOAUTH:
                      r = self._get_authenticated_response(protocol=ad_protocol)
              except TransportError as e:
                  log.debug("Failed to get a response: %s", e)
                  return False, None
              if r.status_code in (301, 302) and "location" in r.headers:
                  redirect_url = get_redirect_url(r)
                  if self._redirect_url_is_valid(url=redirect_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=redirect_url)
              if r.status_code == 200:
                  try:
                      ad = Autodiscover.from_bytes(bytes_content=r.content)
                  except ParseError as e:
                      log.debug("Invalid response: %s", e)
                  else:
                      # We got a valid response. Unless this is a URL redirect response, we cache the result
                      if ad.response is None or not ad.response.redirect_url:
                          cache_key = self._cache_key
                          log.debug("Adding cache entry for key %s: %s", cache_key, ad_protocol.service_endpoint)
                          autodiscover_cache[cache_key] = ad_protocol
                      return True, ad
              return False, None

  ### Ancestors

  - BaseAutodiscovery

  ### Class variables

  `var URL_PATH`