OAuth_Configuration_Guide

Introduction

OAuth authentication or what Microsoft calls 'Modern Authentication' is a method of identity management that offers more secure authentication and authorization for users and applications. It replaced 'Basic Authentication' an authentication method that various applications (including Discover Agents and Discovery Attender) utilized to connect to the Microsoft 365 email, SharePoint, and OneDrive. This guide provides configuration details for Gimmal customers planning to switch to modern authentication.

Note: The examples used in this document are geared towards Gimmal Discover, but the main steps are relevant for Discovery Attender as well.

oAuth Configuration

Step 1, Self-Signed Certificate Creation

Create a Self-Signed Certificate using a PowerShell script provided by the Gimmal Support team.
Run PowerShell or PowerShell ISE as an Administrator, then navigate and open the provided script file
Execute the script; the first prompt will be the Common Name (CN) of the certificate

Press Enter to continue; the second and third prompts will be the Start and End (expiration) dates of the certificate

Then press Enter again to continue; the fourth prompt will be to assign a password to this certificate and click OK

Verify that the certificate has been created and exported to the C:\WINDOWS\SYSTEM32 folder

Copy both certificate files to a safe location and make sure you remember the password assigned during the creation of it. This information will be used during the Azure API registration process in Step 3.

Step 2, App Registration in Microsoft Azure

In the left-hand navigation select 'App registrations':

Click on the 'New registration' button:

Fill out the Name and Redirect URI fields as shown in the example below (the user-facing display name Altitude.OAuth.Method.App shown below is an example)

Click the 'Register' button when finished.

Please make sure to make note of the 'Application (client) ID' and 'Directory (tenant) ID'. The value for the Application (tenant) ID will vary from SharePoint/OneDrive to EWS.

Step 3, OAuth Permissions Setup

The section details the steps that must be taken in the Azure Active Directory administration portal to register the OAuth service, make it available, and assign the appropriate application permissions.

Select 'Authentication' - then checkmark both boxes under the Implicit grant section:

Certificates & secrets - click the 'Upload certificate' button then navigate to the folder path where the certificate created in Step 1 of this document is stored (look for the file with a .cer extension). Click the Add button to continue:

Step 3.1, Adding SharePoint or OneDrive permissions

Click on the 'Add a permission' button

Scroll down and select 'SharePoint':

Select the 'Application permissions' option. Then click the down arrows to expand both the 'Sites' and 'User' sections, and select the 'Sites.Manage.All' and 'User.Read.All' checkboxes

Click the 'Add permissions' button to finish

The SharePoint/OneDrive permissions should resemble this:

Step 3.2, Adding Exchange permissions

Click on the 'Add a permission' button

Follow the three steps outlined in red on the diagram below:

1. 'Click on 'APIs my organization uses'.
2. Type 'Office 365' in the search bar and hit enter.
3. Click on the 'Office 365 Exchange Online' option.

Select the 'Application permissions' option and select the 'full_access_as_app' and 'Exchange.ManageAsApp' checkboxes.

Click the 'Add permissions' button

The Exchange permissions should resemble this:

Note, it is possible to restrict which mailboxes the registered application will have access to. Please refer to this article for more information.

Step 3.3, Expose the API

Click on the 'Add a scope' button

The 'Application ID URI' window will pre-fill with the application id, click Save and Continue to proceed

Fill out the highlighted fields in the 'Add a scope' window, then click the Add scope to proceed

Step 3.4, Adding Additional Owners

Click the 'Add owners' button if additional users need to have access to manage applications and edit application registration

Step 3.5, Configuring Roles and Administrators

For this step, you will need to return to the main Azure dashboard by clicking “Home” in the breadcrumbs in the top-left corner of the screen.

Next, click the “Azure Active Directory” icon as shown below:

Click on the “Roles and Administrator” link.

In the search box near the middle of the page, enter “Exchange Administrator” to bring it to the top, and then click on the line to the right of the role’s name as shown below to display the “Assignments” screen.

Click the “Add Assignments” button.

Next, near the bottom of the screen choose the “No member selected” link under “Select members”.

Then in the “Select a member” window, start typing the name of the registered application that you created until it can be selected.
Check the box to the left of the application.
Finally, choose the “Select” button to save the change.

Click on the “Next” button to continue.

Set the “Assignment type” to “Active”
Check the box next to “Permanently assigned”
Enter the justification for the assignment
Select the “Assign” button to save all updates.

If you added the assignments to the “Global Administrator” role in step 3.5 above, you are done with adding assignments. If you add the assignments to the “Exchange Administrator” role, then you will need to repeat the sequence above for the “Directory Readers” role as well

For more information on modern authentication role permissions, please refer to this Microsoft post:
https://docs.microsoft.com/en-us/powershell/exchange/app-only-auth-powershell-v2?view=exchange-ps#step-5-assign-azure-ad-roles-to-the-application

Check the 'Use Azure Registration Credentials' box, this will gray out the Basic Authentication fields and enable OAuth Authentication. The fields listed in the screenshots below will need to be filled out with the IDs obtained during the App Registration process.

Reminder oAuth authentication is only available in the Discover SharePoint, OneDrive, and EWS Agents. Repeat the above steps to supply authentication credentials for the OneDrive and EWS Agents as well

To apply the newly configured agent permissions, the SharePoint, OneDrive, and/or EWS Agent services will need to be shut down and restarted.

Appendix A – PowerShell Script Example

The following PowerShell script example details the commands necessary for creating a self-signed certificate.
#Requires -RunAsAdministrator
<#
.SYNOPSIS
Creates a Self Signed Certificate for use in server to server authentication
.DESCRIPTION
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21
This will create a new self-signed certificate with the common name "CN=MyCert". During creation, you will be asked to provide a password to protect the private key.
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Password (ConvertTo-SecureString -String "MyPassword" -AsPlainText -Force)
This will create a new self-signed certificate with the common name "CN=MyCert". The password as specified in the Password parameter will be used to protect the private key
.EXAMPLE
.\Create-SelfSignedCertificate.ps1 -CommonName "MyCert" -StartDate 2015-11-21 -EndDate 2017-11-21 -Force
This will create a new self signed certificate with the common name "CN=MyCert". During creation you will be asked to provide a password to protect the private key. If there is already a certificate with the common name you specified, it will be removed first.
#>
Param(
[Parameter(Mandatory=$true)]
[string]$CommonName,
[Parameter(Mandatory=$true)]
[DateTime]$StartDate,
[Parameter(Mandatory=$true)]
[DateTime]$EndDate,
[Parameter(Mandatory=$false, HelpMessage="Will overwrite existing certificates")]
[Switch]$Force,
[Parameter(Mandatory=$false)]
[SecureString]$Password
)

DO NOT MODIFY BELOW
function CreateSelfSignedCertificate(){
#Remove and existing certificates with the same common name from personal and root stores
#Need to be very wary of this as could break something
if($CommonName.ToLower().StartsWith("cn="))
{
Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
if($certs -ne $null -and $certs.Length -gt 0)
{
if($Force)
{
foreach($c in $certs)
{
remove-item $c.PSPath
}
} else {
Write-Host -ForegroundColor Red "One or more certificates with the same common name (CN=$CommonName) are already located in the local certificate store. Use -Force to remove them";
return $false
}
}
$name = new-object -com "X509Enrollment.CX500DistinguishedName.1"
$name.Encode("CN=$CommonName", 0)
$key = new-object -com "X509Enrollment.CX509PrivateKey.1"
$key.ProviderName = "Microsoft RSA SChannel Cryptographic Provider"
$key.KeySpec = 1
$key.Length = 2048
$key.SecurityDescriptor = "D:PAI(A;;0xd01f01ff;;;SY)(A;;0xd01f01ff;;;BA)(A;;0x80120089;;;NS)"
$key.MachineContext = 1
$key.ExportPolicy = 1 # This is required to allow the private key to be exported
$key.Create()
$serverauthoid = new-object -com "X509Enrollment.CObjectId.1"
$serverauthoid.InitializeFromValue("1.3.6.1.5.5.7.3.1") # Server Authentication
$ekuoids = new-object -com "X509Enrollment.CObjectIds.1"
$ekuoids.add($serverauthoid)
$ekuext = new-object -com "X509Enrollment.CX509ExtensionEnhancedKeyUsage.1"
$ekuext.InitializeEncode($ekuoids)
$cert = new-object -com "X509Enrollment.CX509CertificateRequestCertificate.1"
$cert.InitializeFromPrivateKey(2, $key, "")
$cert.Subject = $name
$cert.Issuer = $cert.Subject
$cert.NotBefore = $StartDate
$cert.NotAfter = $EndDate
$cert.X509Extensions.Add($ekuext)
$cert.Encode()
$enrollment = new-object -com "X509Enrollment.CX509Enrollment.1"
$enrollment.InitializeFromRequest($cert)
$certdata = $enrollment.CreateRequest(0)
$enrollment.InstallResponse(2, $certdata, 0, "")
return $true
}
function ExportPFXFile()
{
if($CommonName.ToLower().StartsWith("cn="))
{
Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
if($Password -eq $null)
{
$Password = Read-Host -Prompt "Enter Password to protect private key" -AsSecureString
}
$cert = Get-ChildItem -Path Cert:\LocalMachine\my | where-object{$_.Subject -eq "CN=$CommonName"}
Export-PfxCertificate -Cert $cert -Password $Password -FilePath "$($CommonName).pfx"
Export-Certificate -Cert $cert -Type CERT -FilePath "$CommonName.cer"
}
function RemoveCertsFromStore()
{
Once the certificates have been been exported we can safely remove them from the store
if($CommonName.ToLower().StartsWith("cn="))
{
Remove CN from common name
$CommonName = $CommonName.Substring(3)
}
$certs = Get-ChildItem -Path Cert:\LocalMachine\my | Where-Object{$_.Subject -eq "CN=$CommonName"}
foreach($c in $certs)
{
remove-item $c.PSPath
}
}
if(CreateSelfSignedCertificate)
{
ExportPFXFile
RemoveCertsFromStore
}