Microsoft Exchange

the microsoft exchange connector enables automated email operations and management, facilitating efficient communication and incident response within the swimlane ecosystem microsoft exchange is a widely used email and calendaring server, enabling businesses to manage communication and scheduling effectively the microsoft exchange connector for swimlane turbine allows users to automate email management tasks such as deleting, moving, and categorizing emails, as well as sending, replying to, and forwarding messages directly within the swimlane platform this integration streamlines incident response workflows by providing tools to manage and analyze email data, enhancing the efficiency and effectiveness of security operations prerequisites to effectively utilize the microsoft exchange connector with swimlane turbine, ensure you have the following prerequisites ntlm authentication with these parameters server url the url of your microsoft exchange server username identifier your exchange account username password your exchange account password smtp mailbox address the smtp address associated with your mailbox oauth 2 0 client credentials with these parameters url the authorization url for obtaining oauth tokens client id the client identifier assigned to your application client secret the secret key generated for your application tenant id the directory tenant that you want to request permission from smtp mailbox address the smtp address associated with your 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 https //portal azure com/#blade/microsoft aad registeredapps/applicationslistblade 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 https //docs microsoft com/en us/exchange/understanding role based access control exchange 2013 help (role based access control) your account must be configured with the correct permissions for tasks to run correctly required permissions discoverymanagement https //docs microsoft com/en us/exchange/policy and compliance/ediscovery/assign permissions?view=exchserver 2019impersonation https //docs microsoft com/en us/exchange/client developer/exchange web services/how to configure impersonation for exchange online users, you can either use exchange online admin center https //docs microsoft com/en us/exchange/exchange admin center for editing permissions or windows powershell connection https //docs microsoft com/en us/powershell/exchange/exchange online/connect to exchange online powershell/connect to exchange online powershell?view=exchange ps all other users must use the windows powershell connection https //docs microsoft com/en us/powershell/exchange/exchange online/connect to exchange online powershell/connect to exchange online powershell?view=exchange ps 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 https //docs microsoft com/en us/exchange/exchange admin center 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 https //docs microsoft com/en us/powershell/exchange/exchange online/connect to exchange online powershell/connect to exchange online powershell?view=exchange ps 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 https //docs microsoft com/en us/powershell/exchange/exchange online/connect to exchange online powershell/connect to exchange online powershell?view=exchange ps#connect to exchange online 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 https //docs microsoft com/en us/exchange/client developer/exchange web services/how to configure impersonation 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 https //docs microsoft com/en us/exchange/security and compliance/in place ediscovery/assign ediscovery permissions 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 https //ecederstrand github io/exchangelib/exchangelib/items/item html#exchangelib items item itememail specific fields https //ecederstrand github io/exchangelib/exchangelib/items/message html#exchangelib items message message 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 https //docs djangoproject com/en/dev/ref/models/querysets/#field lookups (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\@gmail com mailto\ email\@gmail com ` with a subject containing 'test' { "subject icontains" "test", "sender" "email\@gmail com" } query all emails from ' email\@gmail com mailto\ email\@gmail com ' with subject matching exactly 'test', that are unread { "subject" "test", "sender" "email\@gmail com", "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 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 criteria, with dry run and exception handling options 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 subject string optional parameter for delete emails 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 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 example \[ { "failed" "failed", "not found" "not found", "recipients affected" \[ "user1\@example com", "user2\@example com" ], "success" "success", "wont process" "wont process" } ] 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 output parameter type description attach info object output field attach info attachments array output field attachments file name string name of the resource file string output field 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 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 an email to a designated folder in microsoft exchange by utilizing 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 output parameter type description date moved string output field date moved new message id string unique identifier success string whether the operation was successful example \[ { "date moved" "string", "new message id" "string", "success" "string" } ] reply or forward mail reply to or forward an email in microsoft exchange using a specified template and message id, optionally as a direct reply input argument name type required description files array optional parameter for reply or forward mail file name string required name of the resource 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 output parameter type description sent response string output field sent response time sent string output field time sent example \[ { "sent response" "string", "time sent" "string" } ] restore deleted email restores a deleted email to a specified folder in microsoft exchange using the provided message id 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 output parameter type description date moved string output field date moved new message id string unique identifier success string whether the operation was successful example \[ { "date moved" "string", "new message id" "string", "success" "string" } ] send an email send an email via microsoft exchange with designated recipients and a selected template input argument name type required description attachments array optional parameter for send an email file name string required name of the resource 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 output parameter type description sent email boolean output field sent email time sent string output field time sent 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 output parameter type description date added string output field date added success string whether the operation was successful example \[ { "date added" "string", "success" "string" } ] notes for more details on ntlm authentication, please refer to ntlm authentication https //github com/ecederstrand/exchangelib/blob/7bf720d439bebf65f5e9f2ff2900b5fa9aa6c400/exchangelib/credentials py