O365 Client Credentials flow - Email Authentication

Contents

Introduction

As Microsoft has started to turn of Basic authentication for email protocols for tenants in favor of Modern Authentication (OAuth2) we have implemented one form of this for ECS email using an interactive flow.

We now have implemented the client credentials flow, which requires no user interaction and uses Microsoft Graph for email handling instead of STMP and IMAP.

The benefit for administrators/users is that there only needs to be one client secret provided in the Azure App which then needs to be configured in ECS once and then all the tenant's mailboxes can be used in ECS by just adding them to the ECS configuration.
If there needs to be a restriction on allowed mailboxes, this can be controlled entirely via the Azure admin. For more information about this, please see: Limiting application permissions to specific Exchange Online mailboxes

Also, the expiration is controllable on Azure side and can be set to a maximum of two years (at the time of writing), meaning that when it works, the ECS configuration only needs to be updated once every two years when a new secret needs to be issued.
In comparison, the interactive flow needs a quarterly update, involving user interaction and (most likely) a MFA input - per mailbox!

For Azure administrators

In Azure Active Directory you need to have an application that supports mail using MS Graph with a client secret available.

Application creation

If you do not have the application set up yet, create one (else, proceed to add permissions or adding secrets as needed):

1. Go to "Enterprise applications"
2. Select "+ New application"

1. Then select "+ Create your own application" 

Give it a logical name so you or others can easily identify it in the future and select the correct application type, for us it is "Integrate any other... ".

Application registration and permissions

Now go to the application registration page.

1. Select "Azure Active Directory"  in the main menu
2. Select "App registrations" in the sub menu

3. As you can see here, the application does not have a secret yet. (far right column)
   Now select the application by clicking the name, this will bring you to the application overview page.
   

   Application id

    Also take note of the application id, this is part of the configuration we need. You can copy it now for later use. or from the application overview page which might be easier since it has copy buttons next to the id.
   In our example this is "a0475c6d-6091-4dec-9720-76cfb9e18a8e"  

From this page (after you copied the application id and pasted it somewhere) we will add the needed permissions:

1. Select "API permissions"
2. Select "+ Add a permission" 
3. Select "Microsoft Graph"

On the API sidebar:

1. Select "Application permissions"
   

   Search

   For the next step note that you can do a partially search for "mail." in the search box as show in the screenshot.

2. Select both:
   1. Mail.ReadWrite
   2. Mail.Send

When you confirm your permissions you should see they are added, but not have not been granted access yet.
You can grant access here by clicking on the "Grant admin consent for..."  title.

Application secret

We now are ready to create a secret we can use in ECS to get access to the mailboxes.

1. In the submenu select "Certificates and secrets" 
2. Select "+ New client secret"

On the client secret sidebar:

• Give it a logical description so you or others can easily identify it in the future
• Select the desired expiration, using the "custom " option you can also set a start date if desired

When the secret is generated you will see its value on the page.

• Use the copy button to copy the secret's value - the ID is not relevant.
• Paste it somewhere for later reference