Change an existing Evoko Home install to use modern authentication with Microsoft 365

This article is for changing an existing Evoko Home install, set up with Microsoft 365 using basic authentication, into using modern authentication.

If you are setting up a new Evoko Home install and want to use modern authentication, please see this article instead.

To use modern authentication with EWS for Office 365, you have to register a custom application in the Azure Active Directory for the Office 365 tenant.  When installing Evoko Home you will need both the Tenant ID and Application ID from Azure to complete the configuration with O365. 

Please follow the guide below to gather/create that information.

Article Contents:

1. Preparations
2. Configure the Azure app and collect information
3. Register App for use with oAuth in EWS
4. Change Evoko Home to use modern authentication

1: Preparations

Update Evoko Home

Make sure you run the latest version of Evoko Home. Go to https://download-liso.evoko.se/ to see which version is the most current one.

Update the impersonation management scope

When using modern authentication, the requirements of the impersonation scope for the service account differ from when using basic authentication. If you previously set up a management scope for impersonation, you will need to change the management scope. 

Important! If a management scope for the Evoko Home service account impersonation is already present, modifying it is an absolute requirement. Skipping this step will result in the transition to modern authentication failing with a "The account does not have permission to impersonate the requested user" error message.

If you chose not to use a management scope for the impersonation when setting up Evoko Home, you can continue at step 2: Configure the Azure App and Collect Tenant/Application ID. 

1. Start by connecting to your Office 365 environment via Windows PowerShell and authenticate with your Office 365 admin account. This is typically done by running the following commands:

   ## On the “Execution Policy Change” question type “Y” and press “Enter”.
       Set-ExecutionPolicy RemoteSigned
       
       ## This will prompt a pop-up asking for credentials.
       ## Enter the user name and password for your Office 365 admin account and click “Ok”.
       $UserCredential = Get-Credential
       
       ## Create session
       $Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection
       
       ## Import session
       Import-PSSession $Session

2. Find your current management scope. If you don't know the name, you can list your current management scopes with:

   Get-ManagementScope

3. When you have found your scope, use this command to see the details: 

   Get-ManagementScope ResourceMailboxes | Format-List

   In the above example, our relevant management scope name was ResourceMailboxes. Note the line that says RecipientFilter, which is is what will be edited. If your line is different from the line in the screenshot you have probably created a custom management scope and will need to change it accordingly.
   
   
4. Edit the management scope using this command:

   Set-ManagementScope ResourceMailboxes -RecipientRestrictionFilter "RecipientTypeDetails -eq 'RoomMailbox' -or RecipientTypeDetails -eq 'EquipmentMailbox' -or PrimarySmtpAddress -eq 'service-account@domain.com'"

   Note: Please change service-account@domain.com to the actual service account for your Evoko system.
   The new part of the command is -or PrimarySmtpAddress -eq 'service-account@domain.com', which means the service account is included in the impersonation scope. In practice, this means that the service account is allowed to impersonate itself.
   
   
5. Verify the change by using this command again:

   Get-ManagementScope ResourceMailboxes | Format-List

   
6. Disconnect from the Powershell session:

   Remove-PSSession $Session

For Microsoft 365 Hybrid exchange setup make sure “EvokoHome/*” is listed in the allow list for EWS.

2: Configure the Azure App and Collect Tenant/Application ID.

Find the tenant name or ID for your Office 365 Tenant in Azure Active Directory

You can use either tenant name or ID in the Evoko Home configuration wizard. Note this down for use in the Evoko Home configuration wizard.

Alternative 1: Use the tenant ID 

1. Log in to the Microsoft Office 365 Admin Portal here: https://admin.microsoft.com
2. Open the Azure Active Directory Portal by clicking on Azure Active Directory under Admin Centers.  (click Show All to show Admin Centers if menu is previously hidden)
3. This will open Azure Active Directory admin center Dashboard. You can also visit this dashboard by URL: https://aad.portal.azure.com
4. Click Azure Active Directory in left panel and click Properties under Manage section.
5. Make a note of the Tenant ID your organization is using.  In this case "e6d83800-f44c-46c4-9128-cbc4512a3235" is the Tenant ID. 

Alternative 2: Use the tenant name

When you signed up for Office 365, Microsoft generated a unique tenant name for your tenant. It is in the form of “<customer id>.onmicrosoft.com”. You can also find this in “Domains” section under “Setup” in the Office 365 Admin Portal. There will be only one domain with suffix “onmicrosoft.com”.
Success! You have the information needed for Office 365 Azure AD Tenant ID.

3: Register App for use with oAuth in EWS

1. In the Azure AD portal, under Azure Active Directory click App Registrations to open the App registrations blade.
   
2. Click the New Registration button. Fill in the name and redirect URL as https://localhost and click Register.
   
3. Once the application is created, you can see the details page. Make a note of “Application (client) ID” value for the Evoko Home configuration wizard.
   
   
4. Click on Authentication. Scroll down and enable Allow Public Client Flows by selecting Yes.  Press Save
   
   
5. Once saved you can access your newly created App Registration by clicking on Azure Active Directory.  Then App Registrations.  Then Owned Applications.  Here in this screenshot you see "Evoko Liso oAuth Configuration" as the name.
6. After clicking on the display name of the App you should land on the overview page.  
7. Under manage you should be able to see API permissions now. Click on API Permissions.
8. Click Add a permission button.
9. Click on APIs my organization uses. Search for "Office" and Press "Office 365 Exchange Online.
10. In the permission selection page, select “Delegated Permission”, which will open the list of permissions for Delegated access. Expand “EWS” and select “EWS.AccessAsUser.All”. Click the Add permission button.
11. You should now see the application permissions.
    
    

4: Change Evoko Home to use modern authentication

1. Open the Evoko Home Global Settings and click Change under the Office 365 service account section:
   
   
   
2. Under "Office 365 Authentication Method", click the dropdown and select Modern (oAuth):
   
   
   
3. Copy and Paste the Tenant ID and Application ID from the previous steps for the appropriate fields and click “Save”.
   
   
   
4. The wizard will now wait for you to log in using the provided URL (https://microsoft.com/devicelogin) and provided code. It's important that you log on using the service account used with Evoko Home. 
   
   
   
5. On the provided URL, enter the code from the wizard and click Next
   
6. Once you sign in using the service account credentials, it will prompt for the consent dialog. This happens only for the first login to this application. Subsequent login remembers the consent.  Review the dialog and click "Accept".
7. You should now see the following screen which informs you to safely close this window.
8. Success! You have now completed the setup with Modern Auth!