Microsoft Exchange

The Microsoft Exchange connector enables streamlined email management and automation directly within the Swimlane Turbine platform, facilitating enhanced security and operational efficiency.

Microsoft Exchange is a widely-used email and calendaring service that enables efficient communication and collaboration within organizations. The Microsoft Exchange Connector for Swimlane Turbine provides a suite of actions to manage email operations, automate incident response, and streamline workflow processes directly within the Swimlane platform. By integrating with Microsoft Exchange, users can perform actions such as deleting emails, exporting email content, retrieving email metadata, and sending emails programmatically, enhancing the capabilities of security automation and improving response times to potential threats.

Prerequisites

To utilize the Microsoft Exchange connector for Swimlane Turbine, ensure you have the following prerequisites:

OAuth 2.0 client credentials authentication with these parameters:

URL: Endpoint for the Microsoft Exchange server

Client ID: Unique identifier for the application registration

Client Secret: Secret key generated during application registration

Tenant ID: Directory ID of the Azure AD tenant

SMTP Mailbox Address: Email address associated with the mailbox

HTTP Basic (NTLM) Authentication with these parameters:

Server URL: Endpoint for the Microsoft Exchange server

Username Identifier: User account name for server access

Password: Corresponding password for the user account

SMTP Mailbox Address: Email address associated with the mailbox

NTLM Authentication

NTLM authentication is only available for Exchange on-premises servers.

Graph Confidential Client

This authentication method allows you to authenticate using an Azure application.

Recommended Application Permissions:

EWS_AccessAsUser.All (Delegated)

full_access_as_app (Application, Grand admin consent for organization)

In order to set up the asset, you need the following:

Azure Application Client ID

Azure Application Client Secret

Azure Tenant ID

Steps to create the Azure app:

Go to the App Registration page in the Azure portal.

Click New Registration.

Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.

Navigate to the API permissions tab on the left navigation menu.

Select Add a permission.

Select the APIs my organization uses tab and search for "Office 365 Exchange Online".

Select Application permissions and check the box next to full_access_as_app.

Select Delegated permissions and check the EWS.AccessAsUser.All box.

Click the Add permissions button at the bottom of the page.

Select Grant admin consent for your organization, then your permissions should look as below.

Navigate to the Certificates & secrets tab and select New client secret.

Fill out the description and expiration, then click the Add button at the bottom.

The Value of the secret you just created is the Client Secret needed for the Swimlane asset.

Navigate to the Overview tab on the left menu.

The Client ID and Tenant ID needed in the asset are shown on this page.

The Client ID, Tenant ID, and Client Secret described in the steps above are the credentials you need for the asset.

Email Account Permission Setup

Microsoft Exchange uses RBAC Permissions (Role-Based Access Control). Your account must be configured with the correct permissions for tasks to run correctly. Required permissions:

DiscoveryManagement

Impersonation

For Exchange Online users, you can either use Exchange Online Admin Center for editing permissions or Windows Powershell connection.

All other users must use the Windows Powershell connection.

Note: These permissions are only required for the Delete from All Mailboxes task. You can still use the connector even if they are not configured.

Note: After setting permissions, it may take a couple of hours for the permissions to propagate within Exchange.

Setting Up Permissions Using Exchange Online Admin Center

Follow the instructions here to get to the Exchange Admin Center.

Click permissions.

Under Admin Roles, select Discovery Management and click the pencil icon to edit.

A dialogue box will appear. In the dialogue box, under Members, click the plus icon to add a member.

Search for and add the user, then click Ok.

Click Save.

Under Admin Roles, search for a role called ApplicationImpersonation. If this role does not exist, you must use Powershell to configure the Impersonation permission, which is detailed in the section below.

Click the pencil icon for ApplicationImpersonation and follow steps 4-6.

Setting Up Permissions Using Powershell

On a Microsoft Windows computer, open an Administrator Command Prompt. Note: To open a program as an administrator, right-click and select Run as Administrator and then run winrm get winrm/config/client/auth.

If you do not see the line Basic=True in the output of the command, run the following command to enable Basic Authentication for WinRM: winrm set winrm/config/client/auth @{Basic="true"}

Open Powershell as an administrator, either by searching for it in the Windows menu or running powershell.exe in an administrator command prompt. A list of supported Windows versions can be found here.

In Powershell, enable Exchange's Powershell scripts to configure your local Powershell and run the command Set-ExecutionPolicy RemoteSigned. If prompted, enter 'Y'.

Now run $UserCredential = Get-Credential. Windows will ask you for a username and password. Enter your Exchange username and password. Your username will be your full email address.

Run $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection to connect to Exchange Online's Powershell session. If your Exchange server is in a country other than the US, see the list of URLs under Connect to Exchange and replace the URL in your command. This link also contains information on proxy settings.

If you run into a permission error, check your username and password and go back to step 5.

Import the remote session into your local shell using Import-PSSession $Session -DisableNameChecking.

Now that Powershell is connected and authenticated, you can modify user and group permissions. You will be modifying only one user in these steps. To see how to modify multiple users or groups, see this link.

Impersonation Permissions

Run the following command to create a new management scope, replacing MYCUSTOMSCOPENAME with a scope name such as SwimlaneImpersonationScope. Also, replace FILTERCHANGEME with a filter to select the user you'd like to grant the permissions. New-ManagementScope -Name:MYCUSTOMSCOPENAME -RecipientRestrictionFilter:FILTERCHANGEME For example, to create a new management scope called SwimlaneScope for the user john your command would look like this: New-ManagementScope -Name:SwimlaneScope -RecipientRestrictionFilter:"Name -eq 'john'"

If the command completes successfully, you will see a printout description of your new Management Scope in table-like form.

Now to apply the ApplicationImpersonation role to the user, run the following command, replacing CUSTOMNAME with a name for the Management Role, such as SwimlaneMgmtRole. Also, replace MYACCOUNTHERE with the name of your account, e.g. john. Replace SCOPENAMEFROMABOVE with the name of the Management Scope you created in step 10.

New-ManagementRoleAssignment -Name:CUSTOMNAME -Role:ApplicationImpersonation -User:MYACCOUNTHERE -CustomRecipientWriteScope:SCOPENAMEFROMABOVE

For example, to create a new role assignment for the Management Scope SwimlaneScope for the user integrations called SwimlaneMgmtRole with the role ApplicationImpersonation you would run New-ManagementRoleAssignment -Name:SwimlaneMgmtRole -Role:ApplicationImpersonation -User:integrations -CustomRecipientWriteScope:SwimlaneScope.

To add Discovery Management Permissions using Powershell, skip step 5 and proceed to the section below.

To stop editing permissions, run the command Remove-PSSession $Session. Otherwise, you may run out of allowed sessions to Exchange and will have to wait until they expire.

Discovery Management Permissions

Original Instructions here.

Run the command Add-RoleGroupMember -Identity "Discovery Management" -Member MYUSERNAME and replace MYUSERNAME with the username who you want to grant permissions to. For example, to grant this permission to a user called integrations run: Add-RoleGroupMember -Identity "Discovery Management" -Member integrations

To add Impersonation Permissions using Powershell, skip step 3 and proceed to the section above.

To stop editing permissions, run the command Remove-PSSession $Session. Otherwise, you may run out of allowed sessions to Exchange and have to wait until they expire.

Capabilities

The Microsoft Exchange connector has the following capabilities:

Get Email Metadata

Delete from All Mailboxes

Set Email Category

Move Email to Folder

Reply to Email with Template

Send an Email

Limitations

Known Errors

Error AADSTS50076: Due to a configuration change made by your administrator, or because you moved to a new location, you must use multi-factor authentication to access

See the Graph Public Client section for instructions on how to resolve this error.

ExchangeImpersonation SOAP header must be present for this type of OAuth token.

See the Graph Confidential Client section for instructions on how to resolve this error.

Input details

Folder Name

Here is an example of how you can use the Folder Name input. In this example, you have an Exchange mailbox like this:

├── Inbox
│       └── InboxSubFolder
└── CustomFolder
           └── SubCustomFolder

If you want to retrieve mail from InboxSubFolder, make sure that Folder Name is Inbox/InboxSubFolder.

To retrieve mail from CustomFolder, change Folder Name to CustomFolder.

To retrieve mail from SubCustomFolder, rename Folder Name to CustomFolder/SubCustomFolder.

Note: This task does not support folders with '/' in their name.

JSON Querystrings

Search Query String is a legacy input, JSON Query String should be used for any new searches. Searching is modeled after the Django QuerySet API, and a large part of the API is supported. The query is a JSON string where each key:value pair represents an expression in the query. Each expression in the query string takes the form:

"{field}__{operation}": {value} (That’s a double-underscore)

If you are matching a field to an exact value, you can use the form: "{field}": {value}

field: The message field you are querying on, see the fields section below for more details.

operation: The operation to use for the expression, see the operations section below for more details.

value: The desired value to compare to using the operation.

Fields

The Instance variables in these two links are all the fields you can search/sort on:

General Fields

Email Specific Fields

Non-basic fields are not able to be used in the query (such as attachments, headers, effectiverights, etc..)

Operations

The query string is based on the Django QuerySet API. In the QuerySet API, operations are called "lookups". Documentation for all the lookup options can be found here (Some lookups may not be supported by exchange). Below is a list of common operations you might use:

range
in
not
gt
gte
lt
lte
exact
iexact
contains
icontains
startswith
istartswith
exists

Operations starting with 'i' such as icontains and iexact are case-insensitive

Example JSON Querystrings

Query all emails from '[email protected]` with a subject containing 'test'.

{
    "subject__icontains": "test",
    "sender": "[email protected]"
}

Query all emails from '[email protected]' with subject matching exactly 'test', that are unread

{
    "subject": "test",
    "sender": "[email protected]",
    "is_read": false
}

So for example, to query for an email between 15:05 3/2/2020 and 15:11 3/2/2020 MST, when your Swimlane instance is also MST:

{
    "datetime_received__gte": "2020-03-02T15:05:33",
    "datetime_received__lte": "2020-03-02T15:11:33"
}

But if your Swimlane instance is UTC time, you will need to modify the query by 7 hours:

{
    "datetime_received__gte": "2020-03-02T22:05:33",
    "datetime_received__lte": "2020-03-02T22:11:33"
}

To use a timevalue that is 5 minutes before the current time, use the following format

{
    "datetime_received__gte": "-5 minutes"
}

Move Email to Folder

If you move an email, it will change that email's Message ID. Use the output New Exchange Email ID for the changed ID.

Retrieve Deleted Email

If you retrieve a deleted email, it will change that email's Message ID. Use the output New Exchange Email ID for the changed ID.

Notes

For more details on NTLM Authentication, please refer to NTLM Authentication

Additional Documentation

Microsoft Exchange Connector Documentation

Microsoft Exchange API Documentation

Microsoft Exchange Authentication Guide

Configurations

Microsoft Exchange NTLM Authentication

Authenticates Microsoft Exchange using NTLM Authentication

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
username	Email Address or Username	string	Required
password	Password	string	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional
username_mailbox	Mailbox email address	string	Required
use_impersonate_access	Use Impersonation rights to retrieve mail. If False will use Delegate permissions	boolean	Optional
use_ntlm	Use NTLM for authentication. otherwise, no authentication type will be applied.	boolean	Optional

Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
tenant_id		string	Required
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional
username_mailbox	Mailbox email address	string	Required
full_name	User's full name	string	Optional
use_impersonate	Use Impersonation rights to retrieve mail. If False will use Delegate permissions	boolean	Optional

Actions

Delete Emails

Permanently deletes emails across all inboxes based on specified criteria, with options for dry run and exception handling.

Input

Argument Name	Type	Required	Description
assigner	string	Optional	Parameter for Delete Emails
delete_type	string	Required	Type of the resource
delimiter	string	Optional	Parameter for Delete Emails
dry_run	boolean	Required	Parameter for Delete Emails
folder	string	Optional	Parameter for Delete Emails
ignore_exceptions	boolean	Required	Parameter for Delete Emails
json_querystring	object	Optional	Parameter for Delete Emails
json_querystring.subject	string	Optional	Parameter for Delete Emails
json_querystring.is_read	boolean	Optional	Parameter for Delete Emails
limit	number	Optional	Parameter for Delete Emails
mailbox_to_use	string	Optional	Parameter for Delete Emails
querystring	string	Optional	Parameter for Delete Emails
worker_count	number	Optional	Count value

Input Example

{"assigner":"=","delete_type":"trash","delimiter":",","dry_run":true,"folder":"Inbox","ignore_exceptions":true,"json_querystring":{"subject":"asdf","is_read":false},"limit":5,"querystring":"subject=asdf,is_read=False","worker_count":4}

Output

Parameter	Type	Description
failed	string	Output field: failed
not_found	string	Output field: not_found
recipients_affected	array	Output field: recipients_affected
success	string	Whether the operation was successful
wont_process	string	Output field: wont_process

Output Example

{"failed":"failed","not_found":"not_found","recipients_affected":["[email protected]","[email protected]"],"success":"success","wont_process":"wont_process"}

Export Email as EML

Retrieve and download the raw MIME content of an email from Microsoft Exchange as an .eml file, including body and attachments.

Input

Argument Name	Type	Required	Description
folder_name	string	Optional	The folder where the email is located (e.g., "inbox", "sent", "My Folder"). Defaults to "inbox" if not specified.
mailbox_to_use	string	Optional	The email address of the mailbox to query. If not specified, uses the default mailbox from the connection.
message_id	string	Required	Message ID of the email to export.
file_name	string	Optional	Name of the file to export.

Input Example

{"folder_name":"inbox","message_id":"AAMkAGI2T...AAA=","file_name":"email.eml"}

Output

Parameter	Type	Description
success	boolean	Whether the operation was successful
file	object	Output field: file
file.filename	string	Name of the resource
file.file_data	string	Response data

Output Example

{"success":true,"file":{"filename":"email.eml","file_data":"data:application/octet-stream;base64,..."}}

Get Email Metadata

Retrieve metadata for unread emails from a Microsoft Exchange account, including sender, subject, and timestamps.

Input

Argument Name	Type	Required	Description
assigner	string	Optional	Parameter for Get Email Metadata
delimiter	string	Optional	Parameter for Get Email Metadata
exclude_extensions	array	Optional	Parameter for Get Email Metadata
folder_name	string	Optional	Name of the resource
ignore_errors	boolean	Optional	Error message if any
include_extensions	array	Optional	Parameter for Get Email Metadata
ingest_unread_only	boolean	Optional	Parameter for Get Email Metadata
json_querystring	string	Optional	Parameter for Get Email Metadata
mailbox_to_query	string	Optional	Parameter for Get Email Metadata
number_of_emails	number	Optional	Parameter for Get Email Metadata
order_by	string	Optional	Parameter for Get Email Metadata
querystring	string	Optional	Parameter for Get Email Metadata
save_mail_as	boolean	Optional	Parameter for Get Email Metadata
sender	string	Optional	Parameter for Get Email Metadata
subject	string	Optional	Parameter for Get Email Metadata

Input Example

{"assigner":"=","delimiter":",","exclude_extensions":[".png",".jpg",".jpeg",".gif"],"folder_name":"My Folder","ignore_errors":false,"include_extensions":[".png",".jpg",".jpeg",".gif"],"ingest_unread_only":false,"json_querystring":"asdf","number_of_emails":4,"order_by":"-datetime_received","querystring":"subject=asdf,is_read=False","save_mail_as":true,"sender":"[email protected]","subject":"invoice"}

Output

Parameter	Type	Description
attach_info	object	Output field: attach_info
attachments	array	Output field: attachments
attachments.file_name	string	Name of the resource
attachments.file	string	Output field: attachments.file
attachments_md5	string	Output field: attachments_md5
attachments_sha1	string	Output field: attachments_sha1
attachments_sha256	string	Output field: attachments_sha256
bcc	string	Output field: bcc
cc	string	Output field: cc
date	string	Date value
error	string	Error message if any
exchange_message_id	string	Unique identifier
headers	string	HTTP headers for the request
headers_json	string	HTTP headers for the request
html_body	string	Request body data
id	string	Unique identifier
orig_filename	string	Name of the resource
raw_content	string	Response content
raw_headers	string	HTTP headers for the request
recipients	string	Output field: recipients
reply_to	string	Output field: reply_to
result	string	Result of the operation
rtf_body	string	Request body data
sender	string	Output field: sender
subject	string	Output field: subject

Output Example

{"attach_info":{},"attachments":[],"attachments_md5":"string","attachments_sha1":"string","attachments_sha256":"string","bcc":"string","cc":"string","date":"string","error":"string","exchange_message_id":"string","headers":"string","headers_json":"string","html_body":"string","id":"string","orig_filename":"string"}

Move Email to Folder

Moves a specified email to a designated folder in Microsoft Exchange using the message ID and folder name.

Input

Argument Name	Type	Required	Description
folder	string	Required	Parameter for Move Email to Folder
mailbox_to_use	string	Optional	Parameter for Move Email to Folder
message_id	string	Required	Unique identifier

Input Example

{"folder":"My Folder"}

Output

Parameter	Type	Description
date_moved	string	Output field: date_moved
new_message_id	string	Unique identifier
success	string	Whether the operation was successful

Output Example

{"date_moved":"string","new_message_id":"string","success":"string"}

Reply or Forward Mail

Reply to or forward an email in Microsoft Exchange with a specific template and message ID, with the option to directly reply.

Input

Argument Name	Type	Required	Description
files	array	Optional	Parameter for Reply or Forward Mail
files.file_name	string	Required	Name of the resource
files.file	string	Required	Parameter for Reply or Forward Mail
bcc_recipients	array	Optional	Parameter for Reply or Forward Mail
cc_recipients	array	Optional	Parameter for Reply or Forward Mail
include_senders	boolean	Optional	Parameter for Reply or Forward Mail
mailbox_to_use	string	Optional	Parameter for Reply or Forward Mail
message_id	string	Required	Unique identifier
subject	string	Optional	Parameter for Reply or Forward Mail
template	string	Required	Parameter for Reply or Forward Mail
to_recipients	array	Optional	Parameter for Reply or Forward Mail
use_html	boolean	Optional	Parameter for Reply or Forward Mail
use_reply	boolean	Required	Parameter for Reply or Forward Mail

Input Example

{"include_senders":true,"message_id":"ANQWdKUqanABH47Gj6QKkavSZaDAXfYFNfoKpLyXPJ=K=mX58Q","subject":"This is the subject of my email","template":"Do not respond to this email.","use_html":true,"use_reply":true}

Output

Parameter	Type	Description
sent_response	string	Output field: sent_response
time_sent	string	Output field: time_sent

Output Example

{"sent_response":"string","time_sent":"string"}

Restore Deleted Email

Restores a deleted email to a specified folder in Microsoft Exchange using the message ID provided.

Input

Argument Name	Type	Required	Description
folder_to_restore_email	string	Required	Parameter for Restore Deleted Email
mailbox_to_use	string	Optional	Parameter for Restore Deleted Email
message_id	string	Required	Unique identifier

Input Example

{"message_id":"AAMkAD...HAAA="}

Output

Parameter	Type	Description
date_moved	string	Output field: date_moved
new_message_id	string	Unique identifier
success	string	Whether the operation was successful

Output Example

{"date_moved":"string","new_message_id":"string","success":"string"}

Send An Email

Send an email through Microsoft Exchange using specified recipients and a chosen template.

Input

Argument Name	Type	Required	Description
attachments	array	Optional	Parameter for Send An Email
attachments.file_name	string	Required	Name of the resource
attachments.file	string	Required	Parameter for Send An Email
bcc_recipients	array	Optional	Parameter for Send An Email
ccs	array	Optional	Parameter for Send An Email
mailbox_to_use	string	Optional	Parameter for Send An Email
recipients	array	Required	Parameter for Send An Email
subject	string	Optional	Parameter for Send An Email
template	string	Required	Parameter for Send An Email
use_html	boolean	Optional	Parameter for Send An Email
use_impersonate	boolean	Optional	Parameter for Send An Email

Input Example

{"subject":"This is the subject of my email","template":"Do not respond to this email.","use_html":true,"use_impersonate":false}

Output

Parameter	Type	Description
sent_email	boolean	Output field: sent_email
time_sent	string	Output field: time_sent

Output Example

{"sent_email":true,"time_sent":"2025-01-09T07:50:21.485049+00:00"}

Set Email Category

Assign a specified category to an email in Microsoft Exchange using the message ID and category name.

Input

Argument Name	Type	Required	Description
category	array	Required	Parameter for Set Email Category
clear	boolean	Optional	Parameter for Set Email Category
message_id	string	Required	Unique identifier
override	boolean	Optional	Unique identifier

Input Example

{"category":["MyCategory"],"clear":true,"message_id":"AAMkADMxZmU3ZWQ4LTMzNGItNGY3ZC1iM2UxLWM3MDQzOGVjMzlkNwBGAAAAAAAGYPwuVwMWSrFeyLv6XHMzBwCBJRT7/oiDTLpLg45RvPkCAAAAAAEMAACBJRT9/oiDTLpLg45RvPkCAAAf+jMxAAA=","override":false}

Output

Parameter	Type	Description
date_added	string	Output field: date_added
success	string	Whether the operation was successful

Output Example

{"date_added":"string","success":"string"}

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT