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 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 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 https //docs microsoft com/en us/exchange/policy and compliance/ediscovery/assign permissions?view=exchserver 2019 https //docs microsoft com/en us/exchange/client developer/exchange web services/how to configure impersonation for exchange online users, you can either use https //docs microsoft com/en us/exchange/exchange admin center for editing permissions or 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 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 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 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 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 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 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 https //ecederstrand github io/exchangelib/exchangelib/items/item html#exchangelib items item item 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 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 ' mailto\ email\@gmail com ` with a subject containing 'test' { "subject icontains" "test", "sender" "email\@gmail com" } query all emails from ' 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 notes for more details on ntlm authentication, please refer to https //github com/ecederstrand/exchangelib/blob/7bf720d439bebf65f5e9f2ff2900b5fa9aa6c400/exchangelib/credentials py 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" \["user1\@example com","user2\@example com"],"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" "mike\@school edu","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