root
/
elasticsearch
mirror of https://github.com/elastic/elasticsearch.git
1
0
Fork 0
Code Issues Actions 1 Packages Projects Releases Wiki Activity
elasticsearch/docs/reference/search-connectors/es-connectors-outlook.md

13 KiB
Raw Blame History

navigation_title mapped_pages
Outlook
https://www.elastic.co/guide/en/elasticsearch/reference/current/es-connectors-outlook.html

Elastic Outlook connector reference [es-connectors-outlook]

The Elastic Outlook connector is built with the Elastic connector framework and is available as a self-managed self-managed connector.

Self-managed connector reference [es-connectors-outlook-connector-client-reference]

Availability and prerequisites [es-connectors-outlook-client-availability-and-prerequisites]

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

Create a Outlook connector [es-connectors-outlook-create-connector-client]

Use the UI [es-connectors-outlook-client-create-use-the-ui]

To create a new Outlook connector:

  1. In the Kibana UI, navigate to the Search → Content → Connectors page from the main menu, or use the global search field.
  2. Follow the instructions to create a new Outlook self-managed connector.

Use the API [es-connectors-outlook-client-create-use-the-api]

You can use the {{es}} Create connector API to create a new self-managed Outlook self-managed connector.

For example:

PUT _connector/my-outlook-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Outlook",
  "service_type": "outlook"
}

:::::{dropdown} 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 {{es}} API documentation for details of all available Connector APIs.

Usage [es-connectors-outlook-client-usage]

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

For additional operations, see Connectors UI in {{kib}}.

Connecting to Outlook [es-connectors-outlook-client-connecting-to-outlook]

Outlook connector supports both cloud (Office365 Outlook) and on-premises (Exchange Server) platforms.

Connect to Exchange Server [es-connectors-outlook-client-connect-to-exchange-server]

In order to connect to Exchange server, the connector fetches Active Directory users with the help of ldap3 python library.

Connect to Office365 Outlook (Outlook Cloud) [es-connectors-outlook-client-connect-to-office365-outlook-outlook-cloud]

To integrate with the Outlook connector using Azure, follow these steps to create and configure an Azure application:

  1. Navigate to the Azure Portal and log in using your credentials.

  2. Click on App registrations to register a new application.

  3. Navigate to the Overview tab. Make a note of the Client ID and Tenant ID.

  4. Click on the Certificates & secrets tab and create a new client secret. Keep this secret handy.

  5. Go to the API permissions tab.

    • Click on "Add permissions."
    • Choose "APIs my organization uses."
    • Search for and select "Office 365 Exchange Online."
    • Add the full_access_as_app application permission.

You can now use the Client ID, Tenant ID, and Client Secret you’ve noted to configure the Outlook connector.

Configuration [es-connectors-outlook-client-configuration]

data_source
(required) Dropdown to determine Outlook platform type: outlook_cloud or outlook_server. Default value is outlook_cloud.
tenant_id
(required if data source is outlook_cloud) The Tenant ID for the Azure account hosting the Outlook instance.
client_id
(required if data source is outlook_cloud) The Client ID to authenticate with Outlook instance.
client_secret
(required if data source is outlook_cloud) The Client Secret value to authenticate with Outlook instance.
exchange_server
(required if data source is outlook_server) IP address to connect with Exchange server. Example: 127.0.0.1
active_directory_server
(required if data source is outlook_server) IP address to fetch users from Exchange Active Directory to fetch data. Example: 127.0.0.1
username
(required if data source is outlook_server) Username to authenticate with Exchange server.
password
(required if data source is outlook_server) Password to authenticate with Exchange server.
domain
(required if data source is outlook_server) Domain name for Exchange server users such as gmail.com or exchange.local.
ssl_enabled
Whether SSL verification will be enabled. Default value is False. Note: This configuration is applicable for Outlook Server only.
ssl_ca
(required if ssl is enabled) Content of SSL certificate. Example certificate: 
-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----
use_text_extraction_service
Use self-hosted content extraction service. Default value is False.
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.

Note: This configuration is applicable for Outlook Server only.

Deployment using Docker [es-connectors-outlook-client-client-docker]

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

::::{dropdown} 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/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.

::::

::::{dropdown} 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: outlook
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # 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 simply uncommenting specific settings in the configuration file and modifying their values.

::::

::::{dropdown} 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.0.0 \
/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 [es-connectors-outlook-client-content-extraction]

Refer to Content extraction.

Documents and syncs [es-connectors-outlook-client-documents-and-syncs]

The connector syncs the following objects and entities:

  • Mails

    • Inbox Mails
    • Sent Mails
    • Archive Mails
    • Junk Mails

  • 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. All documents indexed to an Elastic deployment will be visible to all users with access to that Elastic Deployment.

::::

Sync types [es-connectors-outlook-client-sync-types]

Full syncs are supported by default for all connectors.

This connector also supports incremental syncs.

Document level security [es-connectors-outlook-client-document-level-security]

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.

::::

Sync rules [es-connectors-outlook-client-sync-rules]

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

Advanced Sync Rules [es-connectors-outlook-client-advanced-sync-rules]

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

Connector Client operations [es-connectors-outlook-client-connector-client-operations]

End-to-end Testing [es-connectors-outlook-client-end-to-end-testing]

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

Known issues [es-connectors-outlook-client-known-issues]

There are currently no known issues for this connector. Refer to Known issues for a list of known issues for all connectors.

Troubleshooting [es-connectors-outlook-client-troubleshooting]

See Troubleshooting.

Security [es-connectors-outlook-client-security]

See Security.

Framework and source [es-connectors-outlook-client-source]

This connector is included in the Elastic connector framework.

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