Configuring EWS O365 Self-Deployed Instance and Limiting Mailbox Access

[elmitchell]

XSOAR supports many different email integrations that can be configured in the platform but for today we are going to focus on EWS O365 integration using a self-deployed application. We often get a lot of questions regarding the configuration for this integration and how to then limit access of the application, so I figured this would be the perfect way to quell all of your Exchange Administrators' concerns and answer all of their questions in one swift go.

First, you will need someone with access to register applications in Azure. In the Azure Active Directory admin center go to App Registrations and then choose New Registration at the top of the page as seen in the below image:

Now give your application a name, select the supported account types (for this instance we use Accounts in this organizational directory only), and then finally the redirect URI (for this instance we used Public Client/Native and the URL as https://login.microsoftonline.com/common/oauth2/nativeclient). Now click register to complete the app registration. Once the app is registered you will want to copy the Application (client) ID and the Directory (tenant) ID as you will need these to set up the EWS O365 integration in XSOAR.

Now you will need to configure the correct application permissions for the newly created app. XSOAR EWS O365 integration requires full_access_as_app permission for Office 365 Exchange Online. To configure this we will follow the Microsoft steps to configure app-only authentication. Once you complete these steps your Configured Permissions section for your app should be similar to the below figure.

At this point you should have registered your application in Azure, copied your application ID, tenant ID, and Secret. Now we are ready to configure the XSOAR EWS O365 integration. In XSOAR make sure you have already downloaded the EWS content pack from the marketplace. Now go to Settings > Integrations > Instances. Find the EWS O365 integration and click Add Instance. Now you will fill out the Application ID,  Tenant ID, Application Secret, and Email Address. Note that the email address is the mailbox that you want to fetch emails from and the Application Secret is the Client Secret value that was created in the Azure application. 

The last important setting you want to make sure is checked is Use a self deployed Azure Application. Now you can click the test button and it should be successful. Now you can save and exit. I do recommend also running a simple command to confirm you can pull emails from the inbox you set up using a command similar to: !ews-search-mailbox query="From:*" limit="1" target-mailbox="mailbox@test.com". It can take up to an hour for the API permissions to take effect so you may receive an error message if you test immediately after configuring the app.

Now that we have set this up the next question we commonly get is how do we limit this integration to only be able to access one mailbox. The good news is that it is very easy to set this up and only requires a few additional steps. These steps work for both the EWS O365 and the O365 Outlook Mail (Using Graph API) integrations in XSOAR. You will need an exchange admin and they will need to use the Exchange Powershell module to complete these steps. The cmdlet you will need to run will be New-ApplicationAccessPolicy which will allow you to limit the applications access to certain mailboxes. 

First you will want to make sure that the email or emails you want to limit the applications access to are in a Mail-enabled security group. Once you have the mail-enabled security group create you will want to run this command in powershell making sure to update the AppId to the application ID of the app you are using in your XSOAR integration instance and then make sure the PolicyScopeGroupId correlates to the mail-enabled security group you created: 

New-ApplicationAccessPolicy -AccessRight RestrictAccess -AppId "e7e4dbfc-046f-4074-9b3b-2ae8f144f59b" -PolicyScopeGroupId EvenUsers@AppPolicyTest2.com -Description "Restrict this app's access to members of security group EvenUsers."

This should now limit the applications access to the mailbox or mailboxes is the security group you created. This is great if you only want to pull or search emails from a single inbox or even just a small subset of mailboxes. Once you run the above command you can run a test by running: 

Test-ApplicationAccessPolicy -Identity user1@contoso.com -AppId e7e4dbfc-046-4074-9b3b-2ae8f144f59b

Make sure to set the -Identity argument to a mailbox that the application should not have access to. If set up correctly then the test should indicate the application does not have access to that mailbox. These changes can take up to an hour to take effect so if you get an incorrect result when testing please wait up to an hour and test again. After confirming the application access policy is successfully set up you can now go to your XSOAR instance and attempt to access a mailbox that is not in the mail-enable security group you set up for the application policy. You can perform this test by running this command in your playground making sure to change the target-mailbox to a mailbox that you should not be able to access with the integration: !ews-search-mailbox query="From:*" limit="1" target-mailbox="noaccess@test.com". You have now successfully configured the EWS O365 integration and limited its access to specific mailboxes in your organization.