OAuth Client-Credentials-Flow (Certificate Based)

• See Prepare Office 365 for a Riva Graph connection.

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

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.

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.

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.

• Find the Tenant ID and Client ID, Create a Graph Azure application for Riva and Upload certificate .
• In Step 2: Configure the Authentication - Certificates & Secrets Tab

1. On the left menu, select the Certificates & Secrets tab.
2. On the Certificates & Secrets pane that appears to the right, below Certificate, select Upload Certificate.
3. Select the certificate, and add description, and select Add.

1. In the Riva Manager application, on the menu bar, select Setup.
2. In the left pane, under Connection Wizards, select Microsoft Graph.
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: The primary email address for the Riva connection account.
   • 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 "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 that 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.
      

1. In the Riva Manager application, select Next.

The system creates the connection.

2. If the Graph connection has been successfully created, select Finish.