Microsoft Exchange

introduction this guide tells you how to authenticate the microsoft exchange connector in swimlane you can authenticate using one of the following methods oauth 2 0 client credentials (graph confidential client) ntlm authentication (exchange on premises only) you will create an azure application (for oauth), assign required permissions, collect required identifiers, and configure the connector in swimlane prerequisites access requirements you must have permissions to register applications in azure active directory (for oauth 2 0) assign api permissions and grant admin consent (for oauth 2 0) access the exchange server / exchange online environment configure rbac permissions in exchange (for certain tasks) required credentials during setup, you will collect the following based on your authentication method method required credentials notes oauth 2 0 client credentials url, client id, client secret, tenant id, smtp mailbox address uses an azure application with exchange online permissions ntlm authentication server url, username, password, smtp mailbox address exchange on premises only authentication methods overview choose the authentication method based on your exchange environment authentication method when to use? oauth 2 0 client credentials (graph confidential client) recommended for exchange online and oauth based environments using an azure application ntlm authentication only available for exchange on premises servers oauth 2 0 client credentials (graph confidential client) this authentication method allows you to authenticate using an azure application recommended api permissions assign the following permissions to the azure application full access as app (application, grant admin consent for organization) ews accessasuser all / ews accessasuser all (delegated) azure setup take the following steps to create the azure app go to azure portal > azure active directory > app registrations 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 api permissions tab on the left navigation menu select add a permission select 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 add permissions select grant admin consent for your organization navigate to certificates & secrets tab and select new client secret fill out the description and expiration, click add copy and save the secret value you just created this saved value is the client secret needed for the swimlane asset navigate to overview tab on the left menu copy client id and tenant id shown on this page 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 these permissions are only required for the delete from all mailboxes task you can still use the connector even if they are not configured 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 (see the section below) click the pencil icon for applicationimpersonation and follow steps 3 5 setting up permissions using powershell on a microsoft windows computer, open an administrator command prompt 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 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 and enter your exchange username and password your username will be your full email address run the following command to connect to exchange online's powershell session $session = new pssession configurationname microsoft exchange connectionuri https //outlook office365 com/powershell liveid/ credential $usercredential authentication basic allowredirection import the remote session into your local shell using the following command import pssession $session disablenamechecking now that powershell is connected and authenticated, you can modify user and group permissions impersonation permissions run the command new managementscope name\ mycustomscopename recipientrestrictionfilter\ filterchangeme to create a new management scope and replace 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 for example to create a new management scope called swimlanescope for the user john new managementscope name\ swimlanescope recipientrestrictionfilter "name eq 'john'" now apply the applicationimpersonation role to the user by running the following command, replacing customname , myaccounthere , and scopenamefromabove new managementroleassignment name\ customname role\ applicationimpersonation user\ myaccounthere customrecipientwritescope\ scopenamefromabove for example new managementroleassignment name\ swimlanemgmtrole role\ applicationimpersonation user\ integrations customrecipientwritescope\ swimlanescope 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 run the command add rolegroupmember identity "discovery management" member myusername and replace myusername with the username who you want to grant permissions to add rolegroupmember identity "discovery management" member myusername for example, to grant this permission to a user called integrations run add rolegroupmember identity "discovery management" member integrations 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 connector configuration in swimlane configuration oauth 2 0 client credentials log in to turbine from the left hand navigation pane, click orchestration and click assets asset homepage opens click the plus icon to open the configure your connector asset window select microsoft exchange from the asset type list fill in the asset settings and asset input as shown field description required/optional url endpoint for the microsoft exchange server required tenant id directory id of the azure ad tenant required client id client id from azure app registration required client secret client secret from azure app registration required scope optional, leave blank unless specified optional verify ssl enable/disable ssl verification optional http proxy optional proxy configuration optional username mailbox mailbox email address (smtp mailbox address) required full name user's full name optional use impersonate use impersonation rights to retrieve mail if false will use delegate permissions optional fields with marks are required click create microsoft exchange ntlm authentication this authentication method is only available for exchange on premises servers configuration ntlm authentication fill in the asset settings and asset input as shown field description required/optional url endpoint for the microsoft exchange server required username email address or username required password password required verify ssl enable/disable ssl verification optional http proxy optional proxy configuration optional username mailbox mailbox email address (smtp mailbox address) required use impersonate access use impersonation rights to retrieve mail if false will use delegate permissions optional use ntlm use ntlm for authentication otherwise, no authentication type will be applied optional troubleshooting if you encounter an authentication error verify the client id, client secret, and tenant id are correct (oauth 2 0) verify admin consent has been granted for full access as app if you see 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, use a supported delegated authentication method (graph public client) as required by your tenant configuration if you see an exchangeimpersonation soap header must be present for this type of oauth token , verify your configuration matches the graph confidential client setup and that the correct permissions are applied for ntlm, confirm the exchange server is on premises and the username/password are correct after changing exchange rbac permissions, allow time for permissions to propagate within exchange you have successfully authenticated the microsoft exchange connector in swimlane