Exchange Web Services Authorization Flows

Applies to Riva On-Premise.

• Purpose of this article.
• Connecting Office 365 in Riva.
• Restricting which mailboxes an Azure application can access.
  • How does Impersonation Restriction work with OAuth and Riva?
• Selecting and configuring authentication in Exchange for a Riva connection.

Purpose of This Article

• To provide information about the Exchange Web Services (EWS) authorization flows supported by Riva;
• To explain the levels of access that the service account may have;
• To provide a demonstration, showing restriction of service account access to a selected group of mailboxes.
   

Connecting Office 365 in Riva

It is possible to set up an Office 365 connection in Riva using one of the following options:

• OAuth Authorization Code Grant Flow (Client Secrets) is the recommended protocol for use with Riva. This protocol combines a high level of security and configuration options. Administrators can define scopes and allow the application access to a selected group of mailboxes through the Exchange Web Services API.

• OAuth Client Credentials Flow (supports certificates) is as secure as OAuth Authorization Code Grant Flow but doesn’t allow for configuration of restrictions. For example, it is not possible to choose which mailboxes can be accessed through the EWS API, because the permissions are granted directly to the application itself. Consequently, when the app presents a token to a resource, the resource enforces that the app itself has authorization to perform an action, rather than the user.

• Basic Authentication is not recommended; it is considered insecure by current standards. Microsoft moved to decommission Basic Authentication in 2020. New or existing apps will not be able to use Basic Authentication when connecting to Exchange with EWS.

For more information, see

• OAuth Authorization Code Grant Flow (Client Secrets);
• OAuth Client Credentials Flow (supports certificates);
• Basic Authentication.

OAuth Authorization Code Grant Flow

• OAuth permission to access EWS APIs in Exchange Online.

This flow typically requires a Client Secret along with Tenant Id, Application Id, and Reply URL. Currently, Riva requests Access Tokens as a web app, which makes client_secret a required field, as stated by Microsoft.

To change this behaviour, create Mobile and desktop applications redirect URIs in Azure, under the application’s Platform configurations. These redirect URIs do not require a client_secret. For more information, see Microsoft identity platform and OAuth 2.0 authorization code flow.

OAuth Permission to Access EWS APIs in Exchange Online

To use OAuth Authorization Code Grant Flow with Riva, it is recommended to configure the Azure Active Directory App to have Delegated permissions in order to access EWS APIs in Exchange Online.

Apps with a signed-in user can have delegated permissions. Administrators or users can consent to the app's request for permissions. The app can then make API calls while acting as the signed-in user. For more information, see Authenticate an EWS application by using OAuth.

The app will then have the same access to mailboxes as the signed-in user via Exchange Web Services (EWS). Any Application Impersonation roles configured in Exchange for restricting mailbox access will be respected.

Here is an Azure consent page for Riva, configured with delegated permissions. Note the specific permissions requested:

Restricting Which Mailboxes an Azure Application Can Access

• How does Impersonation Restriction work with OAuth and Riva?

If the Azure application accessed by Riva is configured to use delegated permissions, it will access EWS as the signed-in user. With that in mind, it is possible to configure the service account that signs in the Azure application to impersonate a selected number of mailboxes only. This function can be accomplished through the Exchange Management Shell.

How Does Impersonation Restriction work with OAuth and Riva?

Here is an example of impersonation restriction that uses OAuth Authorization Code Grant Flow, Exchange management scopes, and Riva. For complete instructions, refer to Microsoft documentation.

This example discusses the following resources:

• An Azure application with delegated permissions and Web Redirect URI;
• An Exchange service account that can impersonate only specific mailboxes;
• Riva, to test the overall configuration and confirm that the service account is respecting the roles.

For more information, see Prepare Office 365 Exchange permissions for Riva connections.

The first step is to create the Azure app registration. The app will then have the following configuration:

The second step is to configure the service account by following the Microsoft documentation. The account was configured with the following rules:

• The service account (dev-gfx@) will be allowed to impersonate only mailboxes that contain ‘admin’ in the DisplayName;
• Management Scope Created: "GfRestrictedImpersonation";
• Test mailboxes:
  • dev-gf1@ (admin) – Allowed to impersonate
  • dev-bb@ (User1) – Not Allowed
  • dev-el@ (User2) – Not Allowed
     

Management Scope created in Exchange:

Management Role Assignment created in Exchange:

This is an Office 365 connection in Riva On-Premise that uses the OAuth Client Secret authorization method:

The Azure consent page requests permissions:

Riva connection test: Successfully impersonated the mailbox dev-gf1:

Riva connection test: Failed to impersonate the mailbox dev-bb. The service account is not allowed to impersonate this user.

Riva connection test: Failed to impersonate the mailbox dev-el. The service account is not allowed to impersonate this user.

To continue the workflow, enable user consent in Azure as shown, if permitted by your organization:

If administrator approval is mandatory in your organization, you will need to request approval in the dialog box (as shown below). Once the request is approved by your Office 365 administrator, you can complete the OAuth setup as above.

OAuth Client Credentials Flow (Supports Certificates)

OAuth Client Credentials Flow allows a confidential client to use its own credentials to authenticate with another web service. This removes the need to impersonate a user during authentication. The web service can then use a certificate as a credential.

This flow requires “Application Permissions”, which means that after the app authenticates, it gets full access to all of the organization's mailboxes. The scoping features available for Microsoft Graph do not work with the EWS API.

The consent page of an application that requests Application Permissions would show the following message, if administrator approval is not required. Note the permissions requested, compared with that of OAuth Authorization Code Grant Flow:

For more information, see Microsoft identity platform and the OAuth 2.0 client credentials flow.

Basic Authentication

Basic Authentication requires the application to pass a user name and password in order to authenticate and have access to resources. Although simple, it is less secure than Modern Authentication methods like OAuth. Microsoft announced the end of support for Basic Authentication for Exchange Web Services (EWS) to access Exchange Online. Existing customers who use Basic Authentication will have grace period access until mid-2021.

For more information, see End of support for Basic Authentication access to Exchange Online APIs for Office 365 customers and Upcoming changes to Exchange Web Services (EWS) API for Office 365.