View source for Office365 Certificate Based Authentication

Newer versions of UMS requires certificate based authentication in order to connect to your Azure/Entra tenant through the GraphAPI in order to create and maintain users and groups. Below will be a guide how to configure it.

== Prerequisites ==

==== Install/Update Powershell 7 ====

* Run in Powershell

As of writing this, Powershell version 7.6.2 is required to support this kind of authentication.

==== Install needed powershell modules ====
Run these commands in Powershell 7 administrator mode:
 UnInstall-Module -Name ExchangeOnlineManagement -AllVersions -Force
 
 Install-Module -Name ExchangeOnlineManagement -Scope AllUsers -Force
If using the wrong version of ExchangeOnlineManagement, you may experiences errors related to missing or not loaded file or assembly.

==== Create a self-signed certificate ====
Open Powershell 7 as administrator and run the following command:
 $mycert = New-SelfSignedCertificate -DnsName "inlogic.dk" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(5) -KeySpec KeyExchange -FriendlyName "LiveAtEdu Certificate"
Keep in mind that you need to change the DnsName, choose whichever CertStoreLocation fits your needs and that you can give it whatever FriendlyName that you like.

==== Confirm the thumbprint ====
After creating a new certificate, you should note down the certificate thumbprint, as it will be used later on. You can display it with the following command:
 $mycert | Select-Object -Property Subject,Thumbprint,NotBefore,NotAfter

==== Export the certificate ====
Later on, the certificate will need to be uploaded to your App Registration in Azure/Entra. You can export the certificate to .cer with the following command:
 $mycert | Export-Certificate -FilePath "C:\temp\LiveAtEduCertificate.cer"
Note that you can always change the location and name of the certificate file by changing the FilePath value

If you're running multiple UMS instances across different servers, and connecting to the same tenant you will need to export the certificate as a pfx and install it on all instances of UMS where LiveAtEdu_Sync is running. In order to export as PFX, you can use the following command:
 $mycert | Export-PfxCertificate -FilePath "C:\temp\LiveAtEduCertificate.pfx" -Password $(ConvertTo-SecureString -String "P@ssw0Rd1234" -AsPlainText -Force)

==== Link the certificate to the App Registration ====
If this is your first time setting up an App Registration, then go to:

[[MSGraphPermissions#Creating App Registration|MSGraphPermissions]]

If you already have an App Registration, then find it in your Azure/Entra and click "API Permissions":

[[File:App Registration.png|frameless|500x500px]]

Click APIs my organization uses.

Search for Office 365.

Select Office 365 Exchange Online from the results list.

[[File:API Permissions.png|frameless|500x500px]]

Select Application permissions.

Expand Exchange and select Exchange.ManageAsApp.

Click Add permissions.

After you add the permission, it needs to be granted admin consent. This can be identified by the orange warning triangle next to the recently added permission. For this you need either an application administrator or a global administrator to grant access for the permission that you just added. You can identify when it's been granted by a green checkmark next to the permission.

Click on Certificates & secrets.

Click Certificates > Upload certificate.

[[File:Upload Certificate.png|frameless|500x500px]]

Here you need to upload the .cer certificate you created earlier.

Afterwards check if the thumbprint matches the one you noted down earlier.

==== Exchange admin role ====
Click on Menu > Azure Active Directory.

Select Roles and administrators.

Select All roles and search for exchange.

Click on Exchange Administrator.

[[File:Role Permission.png|frameless|500x500px]]

Search for the Azure application.

Select the application from the results.

Click Add.

==== Test the connection ====
In order to validate if the above configuration worked return to powershell 7 and input the following commands:
 $AppId = "Your Client ID of the App Registration"
 $CertificateThumbprint = "Certificate Thumbprint"
 $Organization = "yourorg.onmicrosoft.com"
 Connect-ExchangeOnline -AppId $AppId -CertificateThumbprint $CertificateThumbprint -Organization $Organization

==== Tenant Settings ====
Now input the certificate thumbprint into the Office 365 Tenant Settings in the UMS Configurator:

[[File:Certificate Thumbprint.png|frameless]]