Create & Test a Microsoft Office 365 Connection - Graph & EWS (Client Credentials)

This article applies to Microsoft 365 Graph & EWS

Generate a Certificate

• Certificate requirement.
• Generating a certificate on Windows Server 2016.
• Generating a certificate on Windows Server 2012.

Certificate Requirments

A self-signed certificate is sufficient and recommended for this type of connection unless your organization has a policy that bans the use of such certificates. (For example, your organization might believe that using self-signed certificates may lead to complacency, and using many of them may be more expensive than using signed certificates. For more information, see The hidden costs of self-signed SSL certificates.)

However, if self-signed certificates are used judiciously, they are sufficient when an organization controls both ends of the connection, knows that both ends are secure, controls the connection, and knows that it is secure. For a Riva On-Premise connection to Office 365, that is the case.

• Riva On-Premise is installed on your secure premises and protected from attacks.
• Your organization is securely connected to Office 365.
• The connection between Riva On-Premise and your Office 365 subscription relies on an Application Registration created in the Microsoft Azure portal for your organization. 

Riva On-Premise and your Office 365 subscription are not strangers that need to establish trust through a certificate signed by a trusted third party: both ends of the connection are under your control and secure, and your organization can securely configure the connection; therefore, a self-signed certificate is sufficient for the connection.

Generating a certificate on Windows Server 2016

The Microsoft PowerShell New-SelfSignedCertificate cmdlet can be used on Windows Server 2016 to generate a self-signed certificate for the Riva connection to Office 365.

Microsoft documentation mentions that the cmdlet creates a self-signed certificate "for testing purposes". The real issue is not whether a self-signed certificate could be used for testing or production; it is whether the connection and both ends of the connection are securely under your control. As demonstrated in the Certificate requirement section, a self-signed certificate for a Riva On-Premise connection with Office 365 is secure and sufficient, and in this case, Microsoft's restriction "for testing purposes" does not apply.

We recommend generating, at a minimum, a 2048-bit certificate, based on the SHA256 hash algorithm. The following command is coded to do so.

To generate a certificate with New-SelfSignedCertificate:

1. In PowerShell, log in as an administrator.
2. Enter the following command, replacing {Certificate Name} with the name you want, for example, RivaSyncOAuth. Be sure to use double quotation marks (") before and after the name.

New-SelfSignedCertificate -Subject "{Certificate Name}" -CertStoreLocation "Cert:\LocalMachine" -KeyExportPolicy Exportable -KeySpec Signature -HashAlgorithm sha256 -KeyLength 2048

3. Take note of the Certificate Name and Store Location. Those values will be used in the Riva OAuth connection to Office 365.
4. Close Powershell.

Generating a certificate on Windows Server 2012

On Windows Server 2012, the Microsoft PowerShell New-SelfSignedCertificate cmdlet cannot be used to generate a self-signed certificate for the Riva OAuth connection to Office 365. Some of the required options are not available for the cmdlet on Windows Server 2012.

MakeCert can be used to generate the certificate.

Microsoft's webpage Certificate creation tool (Makecert.exe) mentions that MakeCert creates a self-signed certificate "for testing purposes". The real issue is not whether a self-signed certificate could be used for testing or production; it is whether the connection and both ends of the connection are securely under your control. As demonstrated in the Certificate requirement section, a self-signed certificate for a Riva On-Premise connection with Office 365 is secure and sufficient, and in this case, Microsoft's restriction "for testing purposes" does not apply.

• For an important caution and more information, see Certificate creation tool (Makecert.exe).
• We recommend generating, at a minimum, a 2048-bit certificate, based on the SHA256 hash algorithm. The following command is coded to do so.

To generate a certificate with MakeCert:

• On the command line, issue the following command, replacing {Certificate Name} with the name you want, for example, RivaSyncOAuth. Be sure to use double quotation marks (") before CN= and after the name.

makecert -r -pe -n "CN={Certificate Name}" -ss my -sr LocalMachine -sky Signature -len 2048 -a sha256

The command generates a certificate with the default validity period: from the day the certificate is generated until and including Dec. 31, 2039, 11:59:59 GMT. To specify different dates, use the -b and -e extended options. For more information, see https://msdn.microsoft.com/en-us/library/bfsktky3(vs.80).aspx#Extended%20Options.

Take note of the Certificate Name, Store Name, and Store Location. Those values will be used in the Riva OAuth connection to Office 365.

In Azure, Create and Configure an Application

• For Graph-based Application Registration review Create a Graph Azure Application For Riva. 
• For EWS-based Applcation Registration review Create and Configure OAuth App in Azure. 

Upload the public key to the Azure Application

For Riva to connect to the Azure application the public key needs to be uploaded to the Azure Application. 

1. Export the certificate from the Microsoft Cert Store (without the private key). 
2. In Azure;
   1. Navigate the App Registration
   2. Select the application you previously created. 
   3. Select Certificates & Secrets. 
   4. Select Certificates and select Upload certificate to upload the certificate you previously exported. 

In Riva, Enter the Auth Connection Details 

1. In the Riva Manager application, on the menu bar, select Add Email.
2. Select the email type, Microsoft Graph or Microsoft Office 365. 
3. On the wizard's Welcome page, select Next.
4. On the Connection Details page that appears, select OAuth Certificate 
   
5. Enter the connection details required by the OAuth Certificate-based connection.
   • E-mail Address: This needs to be a valid email address that Riva will use to test the connection. 
   • Client ID:  The ID of the Azure Application Registration that was created for the connection. 
   • Tenant ID:   The Tenant ID obtained from Azure.
   • Store Name: The name of the Certificate Store that contains the certificate used by the connection for OAuth authentication into Office 365.
   • Store Location: The default value is LocalMachine. This is because the Riva Sync Service is installed by default to execute as a "Local System", which does not have access to the CurrentUser store. In order to use the CurrentUser store, the "Log On As" of the Windows Service must be configured to have access to the certificate. At a minimum, both the "Log On As" service user and the user managing Riva would need to have the certificate installed in the CurrentUser store in order to manage Riva. This additional complexity is error-prone and effectively requires that all users who access the server must use the same user identity to manage Riva.
   • Certificate Name:
     • The name of the certificate that is used by the connection for OAuth authentication into Office 365.
     • Select [...]. In the Windows Security window that appears, select the certificate name.
   • Use Proxy: Required only if you need to deploy proxy services. For more information, see Configure "Use Proxy" settings in email connections. 
6. Once you have added the information, select Next. 
7. You will be brought to the login screen for Microsoft 365. You are required to log in with an Admin account that can accept the permissions of the application.
8. Once logged in, accept the permissions of the application. 
9. If the connection is successful, you will be brought back to the Riva Application. Select Finish.