Elastic Exchange Server connector reference

The Elastic Exchange Server connector is built with the Elastic connector framework and is available as a self-managed connector. It syncs mail, contacts, calendar events, tasks, and attachments from on-premises Microsoft Exchange Server.

Note

This connector is the on-premises (server) mode of the Outlook connector, available as its own connector. The outlook_server data source of the Outlook connector is deprecated. Use the Exchange Server connector for on-premises Exchange.

This connector is available as a self-managed connector. To use this connector, satisfy all self-managed connector prerequisites.

To create a new Exchange Server connector:

  1. In the Kibana UI, search for "connectors" using the global search field and choose the "Elasticsearch" connectors.
  2. Follow the instructions to create a new Exchange Server self-managed connector.

You can use the Elasticsearch Create connector API to create a new self-managed Exchange Server connector.

For example:

				PUT _connector/my-exchange-server-connector
					{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Exchange Server",
  "service_type": "exchange_server"
}
You’ll also need to create an API key for the connector to use.
Note

The user needs the cluster privileges manage_api_key, manage_connector and write_connector_secrets to generate API keys programmatically.

To create an API key for the connector:

  1. Run the following command, replacing values where indicated. Note the encoded return values from the response:

    				POST /_security/api_key
					{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

  2. Update your config.yml file with the API key encoded value.

Refer to the Elasticsearch API documentation for details of all available Connector APIs.

To use this connector as a self-managed connector, use the Exchange Server tile from the connectors list OR Customized connector workflow.

For additional operations, see Connectors UI in Kibana.

To connect to Exchange Server, the connector fetches Active Directory users with the help of the ldap3 Python library, then reads each mailbox through Exchange Web Services (EWS).

The account you configure in username and password needs:

  • Permission to read user objects from Active Directory.
  • The Exchange ApplicationImpersonation role for the mailboxes you want to sync. The connector opens each mailbox with impersonation, so valid credentials alone are not enough.
exchange_server
(required) IP address to connect with Exchange Server. Example: 127.0.0.1
active_directory_server
(required) IP address of the Active Directory server used to fetch users. Example: 127.0.0.1
username
(required) Username to authenticate with Exchange Server.
password
(required) Password to authenticate with Exchange Server.
domain
(required) Active Directory domain name, used to look up users. Example: corp.example.com
ssl_enabled
Whether SSL verification will be enabled. Default value is False.
ssl_ca

(required if SSL is enabled) Content of SSL certificate. Example certificate:

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----
sync_all_mail_folders
Indexes mail from the user mail folders in each mailbox, not only Inbox, Sent, Junk, and Archive. Other folders are stored as Mail with a folder_name field. The four default folders keep their existing types. System folders such as Deleted Items, Drafts, Outbox, and search folders are never indexed. Enabling this setting increases sync time, load on Exchange, and index size. Default value is False.
use_text_extraction_service
Use self-hosted content extraction service. Default value is False.
Index full raw email (including headers)
Toggle to index the full raw MIME message. Default value is False. When off, only the email body (preferring text/plain over text/html) and a minimal set of headers (Subject, From, Reply-To, To, Cc, Bcc, Date, Message-ID) are indexed. Routing/authentication headers and binary attachments are dropped. Enable this toggle to restore the passthrough behavior when body extraction misses content.
use_document_level_security

Toggle to enable Document level security (DLS). When enabled:

  • Full syncs will fetch access control lists for each document and store them in the _allow_access_control field.
  • Access control syncs fetch users' access control lists and store them in a separate index.

You can deploy the Exchange Server connector as a self-managed connector using Docker. Follow these instructions.

Step 1: Download sample configuration file

Download the sample configuration file. You can either download it manually or run the following command:

curl https://raw.githubusercontent.com/elastic/connectors/main/app/connectors_service/config.yml.example --output ~/connectors-config/config.yml

Remember to update the --output argument value if your directory name is different, or you want to use a different config file name.

Step 2: Update the configuration file for your self-managed connector

Update the configuration file with the following settings to match your environment:

  • elasticsearch.host
  • elasticsearch.api_key
  • connectors

If you’re running the connector service against a Dockerized version of Elasticsearch and Kibana, your config file will look like this:

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: exchange_server
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA>
  1. Optional. If not provided, the connector will use the elasticsearch.api_key instead

Using the elasticsearch.api_key is the recommended authentication method. However, you can also use elasticsearch.username and elasticsearch.password to authenticate with your Elasticsearch instance.

Note: You can change other default configurations by uncommenting specific settings in the configuration file and modifying their values.

Step 3: Run the Docker image

Run the Docker image with the Connector Service using the following command:

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.5.5 \
/app/bin/elastic-ingest \
-c /config/config.yml

Refer to DOCKER.md in the elastic/connectors repo for more details.

Find all available Docker images in the official registry.

Tip

We also have a quickstart self-managed option using Docker Compose, so you can spin up all required services at once: Elasticsearch, Kibana, and the connectors service. Refer to this README in the elastic/connectors repo for more information.

Content Extraction

Refer to Content extraction.

The connector syncs the following objects and entities:

  • Mails

    • Inbox Mails
    • Sent Mails
    • Archive Mails
    • Junk Mails
    • Mail — other user mail folders, when sync_all_mail_folders is enabled. Includes a folder_name field.

  • Contacts

  • Calendar Events

  • Tasks

  • Attachments

    • Mail Attachments
    • Task Attachments
    • Calendar Attachments
Note
  • Content from files bigger than 10 MB won’t be extracted by default. You can use the self-managed local extraction service to handle larger binary files.
  • Permissions are not synced unless document level security is enabled. When it is not enabled, all documents indexed to an Elastic deployment will be visible to all users with access to that Elastic Deployment.
  • Mailbox discovery uses Active Directory (LDAP), not Microsoft Graph. The connector considers AD user objects that match its LDAP search filters and have a valid mail attribute, then opens each mailbox through Exchange Web Services (EWS). AD accounts without mail, and SMTP addresses with no mailbox on Exchange (including many service accounts), are skipped during sync. Shared mailboxes are synced only when their AD user is discovered and Exchange exposes a mailbox for that address.

Full syncs are supported by default for all connectors.

This connector also supports incremental syncs.

Document level security (DLS) enables you to restrict access to documents based on a user’s permissions. Refer to configuration on this page for how to enable DLS for this connector.

Note

Refer to DLS in Search Applications to learn how to ingest data from a connector with DLS enabled, when building a search application. The example uses SharePoint Online as the data source, but the same steps apply to every connector.

Basic sync rules are identical for all connectors and are available by default.

Advanced sync rules are not available for this connector in the present version.

Note: End-to-end testing is not available in the current version of the connector.

Refer to Known issues for a list of known issues for all connectors. Known issues listed for the Outlook connector that relate to Exchange Server (on-premises) can also affect this connector.

See Troubleshooting.

See Security.

This connector is included in the Elastic connector framework.

View the source code for this connector (branch main, compatible with Elastic 9.6).