Exchange Web Services Authorization Flows

  • Updated

Applies to Riva On-Premise.

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

This flow typically requires a Client Secret along with Tenant IDApplication 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 that redirect URIs in Azure, under the application’s Platform configurations. These redirect URIs do not require a client_secret. For more information, see the Microsoft identity platform and OAuth 2.0 authorization code flow.

platformconfigurations1(1).png
 

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.

ews_accessasuser_all1.png

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

permissionsrequested2.png

Restricting Which Mailboxes an Azure Application Can Access

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 an 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:

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:

azureappconfiguration1.png

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:

managementscope1.png
 

Management Role Assignment created in Exchange:

managementroleassignment1.png
 

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

rivao365wizard1.png
 

The Azure consent page requests permissions:

permissionsrequested2 (1).png
 

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

connectiontestsuccess1(1).png
 

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

connectiontestfail1-1.png
 

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

connectiontestfail2-1.png

Note: If the service account is a non-admin user and a message related to “admin approval” is displayed (as shown below), you can enable the option “Users can consent to apps accessing company data on their behalf” in Azure Active Directory Admin Center. For more information, see Configure how end-users consent to applications.

There are further options for the approval process workflow, and it is also possible to limit the approval for apps based on user groups. For more information, see Microsoft's documentation:

needadminapproval1.png

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

enterpriseapplcations1.png

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.

o365 oauth admin approval.png

o365 oauth admin approval request pending.png

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 will show the following message if administrator approval is not required. Note the permissions requested, compared with that of the OAuth Authorization Code Grant Flow:

oauthapppermissions1.png

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

Basic Authentication

Basic Authentication requires the application to pass a username 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.

Note: These changes to Basic Authentication apply only to the cloud-based Office 365/Exchange Online products; there are no changes to EWS capabilities of on-premises Exchange products.

Was this article helpful?

/

Comments

0 comments

Article is closed for comments.