Evolution-EWS and OAuth2 for outlook.office365.com

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 company 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, as described here. Company accounts can use application specific passwords too, but administrators can disable this feature.

There is not predefined any application to be used at the moment, which has also its advantage, because the company administrators can create their own application and have everything under control.

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

Find the tenant

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

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

  2. choose Azure Active Directory in the list on the left

  3. pick Properties subsection

  4. the Directory ID is the tenant

It can be seen also when:

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

  2. choose Azure Active Directory in the list on the left

  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 Token Endpoint and OAuth 2.0 Authorization Endpoint. 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 Directory ID from above.

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

Create the application

This section describes how to create an application by a company administrator, which will be used by their users.

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

  2. choose Azure Active Directory in the list on the left

  3. pick App registrations subsection

  4. pick New application registrations at the top

    1. enter the Name, which is used to identify itself to users when logging in. It can be anything, thus for example Evolution-EWS-for-Company will do its job. It can be changed later.

    2. change the Application type to Native

    3. set the Redirect URI to the default used by evolution-ews, which is also offered by Microsoft for native applications https://login.microsoftonline.com/common/oauth2/nativeclient

    4. click the Create button at the bottom

  5. Copy the Application ID, it will be used by each evolution-ews client

  6. click the Settings button above the application Display name, which is in Settings | Manifest | Delete bar; it opens a list of other setting options on the right:

    1. Properties and Redirect URIs can be left as they are; these are used to customize the application

    2. choose the Owners section and make sure the administrator is listed as one of them; if not then click Add and add him/her there. This helps to find the application in the 'My Applications' search.

    3. choose the Required permissions part, which is one of the most important parts. It defines what the application can access.

      1. click Add at the top, which will offer two separate sections:

      2. pick Select an API and find Office 365 Exchange Online there and select it. Click Select button at the bottom

      3. pick Select permissions and choose which of them evolution-ews can be granted. There is required to have selected Access mailboxes as the signed-in user via Exchange Web Services

      4. click Select

    4. click Done to save the changes. The API for Office 365 Exchange Online should be added to the list of APIs.

  7. 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 company data on their behalf option in 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 probably 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 company users. That's one of the reasons why evolution-ews doesn't have any predefined application.

Configure the account in Evolution

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

  1. open Evolution
  2. use File->New->Mail Account

  3. enter user name and mail address
  4. uncheck to look up the settings
  5. click Next
  6. choose Exchange Web Services as the account type

  7. use the email address as the username; when you try to change the Authentication type, then the OAuth2 is not listed there yet, because the Host URL is not for outlook.office365.com

  8. fill Host URL as https://outlook.office365.com/EWS/Exchange.asmx

  9. change the Authentication type to OAuth2 (Office365)

  10. check Override Office365 OAuth2 settings box, which will let you set additional values

  11. fill the Tenant, as found and copied in the first chapter above

  12. fill the Application ID, as created and copied in the second chapter above

  13. the Redirect URI can be left empty, in which case the https://login.microsoftonline.com/common/oauth2/nativeclient will be used. If you changed the Redirect URI in your application, then the same should be used here as well

  14. finish the new account wizard

Once done, a window to log in to a Microsoft site will open, with prefilled address from the account Properties. When Signed in, the user is asked to accept access of the created application to its account with all provided privileges as set above, when the application had been created. Once accepted, the access token is received and it's all.

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.

Apps/Evolution/EWS/OAuth2 (last edited 2018-03-02 11:11:20 by MilanCrha)