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. Suggested are these 18 permissions:

           Read all users' basic profiles
           Read user mailbox settings
           Read and write user and shared calendars
           Send mail on behalf of others
           Read and write user and shared mail 
           Read and write user and shared contacts 
           Create, read, update and delete all tasks a user has access to
           Access mailboxes as the signed-in user via Exchange Web Services
           Read and write user mail
           Send mail as a user
           Read and write user calendars
           Read and write user contacts
           Read users' relevant people lists (preview)
           Create, read, update and delete user tasks
           Read and write user and shared contacts
           Read and write user and shared calendars
           Send mail on behalf of others
           Read and write user and shared mail

        There can be added more, or some removed. It's up to the administrator what will be allowed, but at least Access mailboxes as the signed-in user via Exchange Web Services with non-shared read/write permissions are required.

      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.

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-02-14 10:44:59 by MilanCrha)