First Admin Account - Email

Microsoft's Guide: https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-web-app-sign-user-overview
Authorization protocol: OAuth 2.0 (2-legged with Admin Consent)

📘

Organization-wide Access

The Outlook Email Admin connector provides organization-wide access to Outlook Email by requiring consent of an organization's administrator. This connector should not be used for individual or personal email access. See Retrieving User Data for more information about how to get information on every user in the organization.

1. Add the Outlook Email Admin connector in the Xkit platform

• In the Xkit platform, click "New Connector" in the sidebar or at the bottom of the "Connectors" screen.
• Click "Outlook Email Admin". At this point you'll see a callback url, which you'll provide to Microsoft Azure in the next step, and places to input the Client ID and Client Secret that you'll get from Azure after registering your app.

2. Register your application with Microsoft Azure

• Next, in a separate window, sign in to (or create) your Microsoft account with Azure access.
• Click on "Manage Azure Active Directory" and then "App registrations" in the sidebar or visit this link
• Then click "Register an application".
• Input the name of your app.
• Select "Accounts in any organizational directory (Any Azure AD directory - Multitenant)".
• Add the Redirect URI provided by Xkit in Step 1.
• Click "Register".

3. Generate a Client Secret

• Click on "Certificates & secrets" in the sidebar of your registered app in the Azure portal
• Click on "+ New client secret"
• Name the secret however you wish ("Xkit" is a good name) and set the expiration to "Never"
• Copy the generated secret

🚧

Secret available only once

The client secret will disappear after leaving the window. Make sure to copy the secret before leaving this page.

4. Provide Xkit with the credentials

• Paste the Client secret from Step 3 into the "Client Secret" field on Xkit.
• Copy the "Application (client) ID" from the overview page of your created app in the Azure portal paste it into the "Client ID" field on Xkit.
• Click "Save"

5. Add Catalog Settings

• On Xkit, you will see fields to control how your Outlook Email Admin connector appears to users
• (Optionally) Add a description for your connector that will display to your users on viewing your catalog
• Click "Save"

6. Set up API permissions in Xkit

• The "Connector Settings" page includes a list of available scopes for your connector. You can read more about those scopes in the Microsoft Graph permissions reference
• Check the boxes on Xkit next to the permissions you need to build your integration.

7. Set up API permissions on Azure

🚧

Required additional permissions

In addition to the permissions you've selected for your app, you must also include Directory.Read.All in order to use Outlook Email Admin connector. It is depicted as checked when setting up the connector in Xkit.

• Click on "API Permissions" in the Azure Portal sidebar and then click "+ Add a permission"
• Click on "Microsoft Graph" and then click on "Application permissions"
• Under the "Directory" category, select the checkbox next to Directory.Read.All
• Under the "Mail" and "MailboxSettings" categories, select the checkboxes that correspond to the boxes you checked on Xkit in Step 6
• At the bottom of the window, click "Add permissions"

8. Save Xkit Connector

• Click "Save" on the Connector Settings screen in Xkit.

You've now successfully connected Outlook Email Admin with Xkit!

Retrieving User Data

Once you have configured the Outlook Email Admin connector and an admin at an organization has authorized your application, you can retrieve email data for every member of their organization.

To do so, you'll need the User ID for each user in the organization. For example, you can, using the access token provided by Xkit, call the List mailFolders endpoint with the User ID of any user in the organization and receive a list of their mailFolders.

To retrieve every User ID in the organization, you'll need to call the List Users endpoint, which you have access to thanks to the Directory.Read.All permission.