Create a Microsoft 365 EWS OAuth Connection From Riva Cloud

  • Updated

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 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
    ClientCredentials.png
  6. Add a Validation Email. This is any valid email address that we will use to test the connection during creation.
  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. Select Accept.
  10. If successful, you will be brought back to Riva Cloud with a Connection has been configured successfully! message. 
  11. Select OK

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

Note, that previously Microsoft supported Application Access Policies for restricting mailbox access. However, they have announced that Role Base Access Control for Application (RBAC) will replace Application Access policies. To learn more about RBAC for Applications click here

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. 

  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.
 
An alternative method to limited access is to use an Application Access Policy (AAP). Microsoft has indicated that RBAC is designed to replace AAP, however, they have not provided any indication of when that change will be enforced. If you would prefer to use AAP to restrict access, please follow these steps
 

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

NoteMicrosoft has announced that RBAC using ApplicationImpersonation is being deprecated. As of May 2024, new assignments of the ApplicationImpersonation role will no longer be supported and the role will be appreciated at the end of 2025. 

The alternative method for creating connections to Office 365 uses the Client Credentials Flow. To learn more, click here

To learn more about Microsoft's end of support for RBAC/ApplicationImpersonation please read this Microsoft article

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.

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

    Office-365-Connection-page-for -OAuth.png

  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.

    Riva-Cloud-for-Office-365--Permissions-requested-window.png

  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 Office 365 Exchange permissions for a Riva Cloud connection

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.

 

Was this article helpful?

/