Evolution-EWS and OAuth2 for Microsoft 365

Since evolution-ews 3.27.91 users can configure an Office365 account (Host URL pointing to https://outlook.office365.com/EWS/Exchange.asmx) with OAuth2 authentication, which works for organization accounts, if the administrator of that organization allows the access to an application. Users of free accounts at live.com/hotmail.com/outlook.com addresses can also configure EWS account with the same Host URL, but they cannot use OAuth2, it's required to create an application specific password. Organization accounts can use application specific passwords too, but administrators can disable this feature.

There are two existing application IDs, but the organization administrators can create their own application and have everything under their control.

To be able to use OAuth2 with outlook.office365.com server an application ID, which identifies the application which requests access to user data, and a tenant ID, which basically identifies the organization, are required. How to get them and what to do with them in Evolution is written below.

Available application ID

There are created two unverified applications (for testing purposes). They are setup in a way that they can be used by the organizations, though, depending on the organization settings, the administrators may or may not need to approve them first. These applications can be used with the organization tenant ID or with the common (or left empty) tenant ID. Again, it depends on the actual organization settings.

1. 20460e5d-ce91-49af-a3a5-70b6be7486d1 - it has enabled both EWS and Microsoft Graph API usages, but the Graph API is not enabled (in evolution-ews 3.38.x) due to its incompleteness. The application identifies itself as GNOME Evolution. It's preferred in case the Graph API would be used in the future, thus the transition to it will be smooth.

2. 751cf8be-ca07-484b-9308-fac4b9d85eff - it has enabled only the EWS protocol. The application identifies itself as GNOME Evolution EWS.

3. Users can also try application IDs shown at this Microsoft page, like d3590ed6-52b3-4102-aeff-aad2292ab01c, with the Redirect URI set to urn:ietf:wg:oauth:2.0:oob and other values kept empty.

Find the tenant ID

This is for the cases when the common tenant ID does not work for the organization.

Each organization has assigned its directory (tenant) ID, which is used to identify the organization when authenticating the user. How to find out the tenant ID is described here. A short walk-through is:

1. login to https://portal.azure.com

2. click the View button below Manage Azure Active Directory near the top of the page

3. the Overview section (selected by default) shows a Tenant information where is the Tenant ID

It can be seen also when:

1. login to https://portal.azure.com

2. click the View button below Manage Azure Active Directory near the top of the page

3. pick App registrations subsection

4. click Endpoints at the top of the subsection

It opens a table, where can be seen OAuth 2.0 authorization endpoint (v2) and OAuth 2.0 token endpoint (v2). Evolution-ews uses
https://login.microsoftonline.com/$TENANT/oauth2/token
and
https://login.microsoftonline.com/$TENANT/oauth2/authorize,
where the $TENANT is replaced with the same value as the Tenant ID from the above.

If you are a normal user and do not have the required permission to check in the portal.azure.com, you might find the tenant ID in your browser history. Search for URLs containing tenantId=........-....-....-....-.............

Copy this Tenant ID, it'll be used together with Application ID when configuring evolution-ews.

Create the application

This section describes how to create an application by an organization administrator, which will be used by their users. One of the above application IDs usually work, but if the organization administrators would like to limit the access only to the organization-defined apps, then they can create them using the following steps.

A quick start provided by Microsoft can be seen here. Below is shown what values to pick to make it work with evolution-ews.

1. login to https://portal.azure.com as an administrator

2. search for App registrations at the top and select it

3. pick at the top + New registration

4. set the Name and Supported account types - it can be Accounts in this organizational directory only

5. under Redirect URI section set Public client/native (mobile & desktop) as the application type

6. click Register - this opens a page with Essentials (at the mid-top of the window)

7. click on API Permissions on the left side.

   1. then click Add permissions

   2. select APIs my organization uses and choose the Office 365 Exchange Online in the list (search for office in the search box)

   3. to What type of permissions does your application require? use Delegated permissions

   4. expand the EWS node and check EWS.AccessAsUser.All

   5. then click Add permissions

   6. if there's any Microsoft Graph permission, then it can be removed. It's not used by the evolution-ews EWS part. Right now, the only API permission is the Exchange EWS.AccessAsUser.All.

8. click the Authentication section on the left

   1. click on the + Add a platform in the Platform configurations part

   2. select Mobile and desktop applications

   3. select the checkmark beside the https://login.microsoftonline.com/common/oauth2/nativeclient address. If you want to use a different Redirect URI, then you can set it here.

   4. finish this step by clicking the Configure button at the bottom

The application can be authorized for everybody by the administrator by opening the below URL in the browser and logging there with the administrator credentials. Make sure the <TENANT ID HERE> and <APPLICATION ID HERE> are changed to the correct values, eventually also the redirect_uri parameter of the URI (properly encoded) in case it had been changed above:

• https://login.microsoftonline.com/<TENANT ID HERE>/oauth2/authorize?resource=https%3A%2F%2Foutlook.office.com&response_type=code&response_mode=query&prompt=admin_consent&client_id=<APPLICATION ID HERE>&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient

  Depending on the Users can consent to apps accessing organization data on their behalf option in Manage Azure Active Directory->Users->User settings->Enterprise Applications section, either only the administrator can do this (it's when it is set to No (more secure)) or the users can confirm the application access on their own when they are logging in the evolution-ews account (it's when the option is set to Yes, which is the default).

The application can be created as multi-tenant, thus for multiple organizations, but it still requires the administrator to allow its usage for the organization users. That's one of the reasons why evolution-ews doesn't have any predefined application.

Configure the account in Evolution

The application ID and the tenant ID are known now. The only thing is to let Evolution use it.

1. open Evolution

2. use File->New->Mail Account, click Next

3. set your name and email address, uncheck the Look up mail server details... and click Next

4. as Server Type select Exchange Web Services

5. Username might be the same as the email address

6. change the Host URL to https://outlook.office365.com/EWS/Exchange.asmx

7. click the Fetch URL, which will ask for the password and, if successful, it'll fill the OAB URL field (this step is optional, the OAB URL is needed for offline Global Address List (GAL) only)

8. only now change the Authentication type to OAuth2 (Office365)

9. check the Override Office365 OAuth2 settings

10. the administrator/application creator can go to the Overview tab of the registered application (Home > App Registrations > Your application) at https://portal.azure.com and copy from there the Application (client) ID from the Azure site and paste it into the Application ID field in Evolution. Then copy the Directory (tenant) ID and paste it into the Tenant ID field in the Evolution. The Redirect URI can be left empty, unless there had been set a different URI above (in the Azure portal). These settings will be shared with all users accessing the EWS for the organization.

11. finish the New Mail Account wizard with options as you prefer

After this an OAuth2 authentication wizard will show up. Give it the credentials, confirm the usage (unless the application administrator confirmed the usage for the whole organization) and finish the credentials prompt. If things worked properly you should get your Mails, Calendars, Contacts, Memos and Tasks shown in Evolution.

Alternative endpoints

The evolution-ews 3.39.1 allows connecting to alternative Microsoft endpoints, those not being part of the outlook.office365.com. Those can be recognized by using different Host URL, like https://outlook.office365.us/EWS/Exchange.asmx (not a .com, but a .us at the end of the host name). To have the OAuth2 working the user needs to change the options under the Advanced Settings section, as outlined below.

1. Endpoint host - the default (World Wide) endpoint uses login.microsoftonline.com, but the other endpoints use their own address, like login.microsoftonline.us. Change it to the one used for your organization.

2. Redirect URI - it can be left empty, it'll be changed to use the configured Endpoint host in that case, thus for example https://login.microsoftonline.us/common/oauth2/nativeclient.

3. Resource URI - this is used in the token requests. When left empty, evolution-ews uses the same host as the Host URL points to. The default value is https://outlook.office365.com, in case it could not be determined fromt he Host URL.

Troubleshooting

Not every error makes it into the UI. Evolution can be run from a terminal with additional debugging to see what happens in the background. The commands are:

   $ export EWS_DEBUG=2
   $ export OAUTH2_DEBUG=1
   $ evolution

Search for x-ms-diagnostics header in the responses from the server, which contains additional information useful for further debugging.