Configuration steps for Office 365: Microsoft Graph App Configuration

Microsoft Graph App Configuration

This section includes the configuration steps for clients who use Office 365 to access the Incident Responder service.

With this configuration, without admin installed on Outlook desktop, you can start an incident investigation and response for all users, including mobile users.

Important Note: Make sure you have full rights of “Global Exchange Admin” before beginning the steps described in this document. Other roles, including Exchange Admin, are not allowed for this configuration.

1. Log on your Office 365 account: https://admin.microsoft.com/AdminPortal/Home#/users​

2. Select the user who will be the Global Administrator and then click to see their permissions.

Important Note: If no user is set up, then please complete the following steps:

  • In the left hand menu select Users and then Active users

  • Click +Add a user and then fill out the basic information fields required to set up the user, Display name and Username are compulsory. Then click on Next.

  • Select your location and assign product licenses required and then click Next.

  • Under Optional settings, under Roles select Admin center access and tick the checkbox next to Global Admin. Go to Add Profile and complete the fields if needed. Then click Next.

  • Review and finish the new user account. To complete the process, click Finish Adding.

  • The user will now be added to the active users

  • Click Close

3. If the user has already been set up, select this user and under the Account tab, go to Roles and click on Manage Roles.

4. Tick the Global Admin check box and then save changes. The Global Administrator Role for the user has now been created.

5. The next step is to go to register a New Application at the App Registration URL: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade

Figure One: Microsoft Azure Portal

To register a New Application, select App Registrations and then click +New registration. Fill in the required fields and once these are completed, then select Register.

New Application

To register a New Application, select App Registrations and then click +New registration. In the Register an application section:

  • Enter the name of the New application (compulsory field).

  • For Supported account types, select Accounts in this organizational directory only (Auth Secure Login only - Single tenant).

  • For Redirect URL types, in the dropdown menu select Public client/native (mobile & desktop) and then select Register (Leave blank the myapp://auth field).

  • The New Application will appear in the list of App Registrations: click on the title of the New Application.

  • Under Essentials, you will see the following displayed: Application (client) ID Directory (tenant) ID Object ID

  • Please take a note of these as they will be needed later when you set up the New Configuration.

Now we are ready to proceed to the next step: The Application Secret Key.

Application Secret Key

An Application Secret Key is now needed for the New Registration.

On the left hand side under Manage, select Certificates & secrets.

Under Client secrets, select +New client secret.

Add the Description and when it expires. When finished select Add.

A New Application Secret Key will now be created.

Important note: The Application Secret Key will be hidden, so please make sure to copy the secret key before you go to other configuration steps.

Application Permissions

The next step is to add Application Permissions.

To add Application Permissions, go to the Manage menu on the left, select API Permissions and select +Add a permission.

Now click on Microsoft Graph and a new window called Request API permissions will appear. Go to the Select permissions field, add the required permissions:

  • Directory.Read.All

  • Mail.ReadWrite

  • MailboxSettings.ReadWrite

  • User.Read.All (under User)

After adding each permission, click on Update permissions or if you do not want to proceed, click Discard.

After adding the permissions, you have to click on the “Grant admin consent for (user)” button.

What each permission does

Directory.Read.All (Get user list) This allows the app to read data in your organization's directory, such as users, groups and apps. Note: Users may consent to applications that require this permission if the application is registered in their own organization’s tenant.

The platform uses this permission to retrieve the client's user list when the investigation is started, and then to access their email address. The platform gets the users’ email addresses and numbers. For example, when a user finds a suspicious email, the platform can scan all users in the list retrieved.

Mail.ReadWrite (Get users mails) This allows the app to create, read, update, and delete email in user mailboxes. It does not include permission to send mail.

The platform uses this permission to scan and filter users' emails. For example, when the From filter is chosen for investigation, this authorization lists the emails that meet this criterion. In addition, when you send a warning to users, a warning message is added to this email with this authorisation.

This permission helps the platform to scan the contents of the emails to find and match the searched parameters for investigation. For example, it investigates the specific filters that we have specified during the investigation like regex, keywords and etc..

MailboxSettings.ReadWrite (Warning action) This allows the app to create, read, update, and delete user's mailbox settings. It does not include permission to directly send mail, but allows the app to create rules that can forward or redirect messages.

The platform uses this permission to mark emails to which the user wants to send a warning message.

User.Read.All (Get user data) This allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user.

The platform uses this permission to read and filter user information during the scanning process. If user-related filters such as specific users are selected in the scan, the user information may need to be read.

For example, an organisation can initiate an investigation for employees in a particular department.

Testing the Configuration

To test the configuration go to your Dashboard: click on Incident Responder and in the dropdown menu select Mail Configurations:

  • Select the New Configuration button on the right side of the window and choose the mail provider - in this case O365.

Configuration

  • Enter the name for your Configuration.

  • In the Application (client) ID, Application Secret (Key) and Directory (tenant) ID, enter the IDs. and Application Secret Key created earlier in the New Application steps.

  • In Test Email, enter a test email address to test the Configuration.

  • Then click Next.

Test Connectivity

  • The Configuration will now be tested: a green tick will appear next to each step if successful. If a red cross appears, there is an error and please recheck the steps.

  • To complete the test, click on Save.

The New Configuration will now appear in the list of Mail Configurations. To edit or delete the configuration, go to the edit or delete button on the right under the Action column.