Create a Microsoft 365 EWS OAuth Connection From Riva Cloud

Multi-Factor Authentication (MFA)

• If Multi-Factor Authentication (MFA) is required: You'll need to provide an MFA verification code (from your phone or email - for the admin account) when creating the connection.
• Alternatively, you can request your IT department (Exchange/Azure admin) to exempt the Riva service account from needing MFA.

Create the Microsoft 365 OAuth Connection to Riva Cloud - Client Credentials Flow

To create the Microsoft 365 connection in Riva Cloud using the Client Credentials flow, you need the following: 

1. A valid email address so we can validate the connection once it is created. 
2. An Exchange Admin account that can log in and accept the application permissions. 
3. IP whitelisting (optional). 
4. Limit the scope of the application permissions. 

The following are the steps to create the connection via the Riva Cloud UI: 

1. Log into the Riva Cloud account and select "Configure your Email". 
2. On the Select an Email Platform select "Office 365 EWS Connection". 
3. Select "Continue with Email connection". 
4. In the Connection window, there are two options, Client Credentials Method and Auth Code Method. Client Credentials replace Auth Code. 

5. Make sure you are on the Client Credentials Method. 

   

6. Add a Validation Email. This is any valid email address that we will use to test the connection during creation. Note, that to perform connection tests, this user needs to be part of the scoped group. You can make this a generic mailbox if you want. 
7. Select Connect to Microsoft 365. 
8. You will be redirected to the Microsoft 365 login page. You are required to log in with an admin email address that can Accept the application permissions.
9. After login, Permission Request window opens
   
   
    
10. Select Accept.
11. If successful, you will be brought back to Riva Cloud with a Connection has been configured successfully! message. 
12. Select OK. 

Why Admin Consent is Required to Configure the EWS OAuth Connection

When we configure a Microsoft 365 connection using OAuth Client Credentials with Microsoft Exchange Web Services (EWS), the application authenticates independently, without a signed-in user.

Because there is no user context, Microsoft requires the application to be granted an application-level permission called full_access_as_app. This is the only permission supported by EWS for app-only (non-interactive) authentication.

Why admin consent is mandatory

• full_access_as_app is an Application permission, not a delegated (user) permission.

• Application permissions affect the tenant as a whole, not an individual user.

• As a result, Microsoft requires a tenant administrator to explicitly approve (admin consent) this permission before the application can connect.

• Without admin consent, Microsoft will block the EWS OAuth connection.

This requirement is enforced by Microsoft and applies to all vendors and integrations using EWS with Client Credentials.

How access is limited and controlled

While full_access_as_app is broad by default, it does not mean unrestricted access in practice. After admin consent is granted:

• Access can be restricted to specific mailboxes using Microsoft’s mailbox scoping controls (Application Access Policies / RBAC).

• These controls ensure the application can only access approved mailboxes and cannot read or interact with mailboxes outside the agreed scope.

Limit the scope of Mailbox access using Role Base Access Control (RBAC)

To configure RBAC for your application, you will need to use PowerShell connected to Office 365 to set up a New-ManagementScope.

The following steps assume you have a mail-enabled security group configured in Office 365 that the Riva users will belong to (Note that we have tested other group types and this method does not seem to work with those). 

1. Connect to Exchange from Windows PowerShell. To learn how to connect to Exchange Online using PowerShell, please review the Microsoft documentation here. 

2. From PowerShell use the Get-DistributionGroup cmdlet to obtain a list of the distribution groups available in your tenant. Find the one you are going to use and make note of the Name. You will need it later. 

3. Add a New-ManagementScope. This will add a scope to the RecipientRestrictionFilter, in this case, the mail-enabled security group. 

   New-ManagementScope -Name "RivaSync" -RecipientRestrictionFilter {memberofGroup -eq "CN=RivaSecurityGroup20220128151208,OU=rivalabs.onmicrosoft.com,OU=Microsoft Exchange Hosted Organizations,DC=CANPR01A004,DC=PROD,DC=OUTLOOK,DC=COM"}

   Note: You need to use the fully qualified Distinguished Name.  
   

   Get-Group "groupName" | Select-Object -Property DistinguishedName

   1. Name - sets the ManagementScope name. 

   2. RecipientRestrictionFilter - defines the filter that restricts the mailboxes that can be managed by the ManagementScope. 
      

4. Create a New-ServicePrincipal. This sets the ServicePrincipal for the application object in Azure. You will need the Application ID and the Object ID. You can get this from the "Enterprise Application" section in Azure. 

   New-ServicePrincipal -AppId a3324834-eacd-4f3a-8256-7d977a799ffe -ObjectId 3d5bdc46-4b47-4770-8d2e-d0331b19d393 -DisplayName "RBAC RivaSync"

5. Once you have the ServicePrincipal defined, you need to create a New-ManagementRoleAssignement.

   New-ManagementRoleAssignment -Name "RBAC RivaSync" -Role "Application EWS.AccessAsApp" -App a3324834-eacd-4f3a-8256-7d977a799ffe -CustomResourceScope "RivaSync"

   1. The Name is the name of the ServicePrincipal in step 4. 

   2. The role Application EWS.AccessAsApp grants the application access to EWS with full mailbox access. 

   3. The App is the Application ID from Azure. 

   4. The CustomResourceScope is the ManagementScope defined in step 3. 

Now that you have restricted the application access to those mailboxes that are part of the defined security group, Riva will only be able to access those defined mailboxes. 

To test the application RBAC scope, you can run the following PowerShell cmdlet:

Test-ServicePrincipalAuthorization -identity "RBAC RivaSync" -Resource HenriettaM@rivalabs.onmicrosoft.com | Format-Table

Replace "HenriettaM@rivalabs.onmicrosoft.com" with the mailbox you want to test against. 

Note that it can take some time for these permissions to propagate. Therefore, if you run this test immediately after the RBAC scope has been configured, it might not work

Create the Microsoft 365 OAuth Connection to Riva Cloud - Authorization Code Flow

Creating the connection per se is followed by two closely related steps:

1. Create the Office 365 OAuth connection to Riva Cloud.
2. Whitelist the Riva Cloud IP address range.
3. Prepare Office 365 Exchange permissions for the Riva Cloud connection.

Step 1: Create the Microsoft 365 OAuth connection to Riva Cloud

This step creates an OAuth Client Secret to connect to Office 365.

To create the Microsoft 365 OAuth connection:

1. Log in to https://www.rivacloud.com. (Detailed instructions to log in or sign in.)
2. On the Get Started page, select Configure your email.
3. Select the Office 365 logo.
   • If you select the Exchange logo, follow the instructions at Create an Exchange EWS connection: Riva Cloud.

4. On the Connection page that appears, select Connect.

   

   • If you select Use Traditional Authentication, follow the instructions at Create an Exchange EWS connection: Riva Cloud.

5. In one or more Microsoft windows that appear, enter the information required to access the desired Office 365 account.

   Note: The required information may include Multi-Factor Authentication (MFA).

6. If you see this Permissions requested page, select Accept.

   

7. Do one of the following:
   • If the connection setup is successful, select OK. Result: The Office 365 OAuth connection is added to your Riva Cloud account.
   • If you experience an issue, see the following step.

Step 3: Prepare Microsoft 365 Exchange Permissions for Riva Connections

• If you're using Riva Cloud Corporate and/or require impersonation, see Prepare Microsoft 365 Exchange Permissions for Riva Connections.

IP Whitelisting

To ensure a smooth connection, whitelist Riva Cloud IP addresses if your organization's security policies require it. Contact the Riva Success team here for assistance.