support

Articles in this section

How to setup OAuth authentication for Evoko Home with Office 365

Last updated

Contents

Introduction

To use OAuth with EWS for Office 365, You have to register a custom application in Azure Active Directory for Office 365 tenant and gather some information.

Follow this guide to gather the information for the setup wizard for each field in the form.

Note! You might have to upload the certificate files from localhost. If the certificate files do not seem to be uploading correctly and you are contacting the Evoko Home server via http://ip.of.the.server:3000, please try again from the server itself, using http://localhost:3000.

Office 365 Service Account

This is an account which is used to impersonate the resource accounts when calling EWS with oAuth authentication. This is only used in the initial setup process and when changing EWS related settings like importing meeting rooms.

It is recommended that you create a dedicated mailbox for this purpose.

Tenant ID

  1. Login to Office 365 Admin Portal
  2. Open Azure AD Admin Portal by clicking “Azure Active Directory” under Admin Centers

    This will open the Azure Active Directory admin center Dashboard. You can also visit this dashboard by opening this url: https://aad.portal.azure.com


  3. Click Azure Active Directory in left panel and click Properties under “Manage” section.

    Make a note of the Directory ID, in this example 459dde7d-be02-4767-933d-76263442fb00. This is your “Office 365 Azure AD Tenant ID”.

Application ID

  1. In the Azure AD portal, click on  “App Registrations” to open App Registrations blade.
  2. Click on New Application Registration (existing applications can be viewed by clicking the “View all applications” button).
  3. Fill in the necessary information and click Create.
  4. Once the application is created, you can see the details page. Click the “Settings” button.
  5. In the settings blade, click "Required permissions".
  6. Click “Add” in the Required permissions blade, then click on "1 Select an API" and select "Office 365 Exchange Online (Microsoft.Exchange)".
  7. Click select and then click “2 Select permissions” if it is not selected automatically
  8. Under “Application Permissions” inside Enable Access blade, enable “Use Exchange Web Services with full access to all mailboxes” then click select
  9. Click done
  10. We also need to grant the privilege to app using admin consent, to do this without needing to open the consent screen by app, click "Grant Permissions” after selecting "Office 365 Exchange Online (Microsoft.Exchange)" in the "Required Permissions" blade.
  11. Click yes to grant required permission. It may take a few minutes to grant permission and propagate the new settings to all Azure systems.
  12. Open Keys blade by clicking Keys in Settings blade. Then click on “Upload Public Key”. You will need to generate a public private key pair to use with oAuth.
  13. Click inside the field or folder icon button for selecting certificate public key file (cert.pem as generated per instruction) from disk.
  14. Once selected file in file browser, it will upload key file and wait for save action.
  15. Click Save button on Keys blade, public key hash will be shown under Thumbprint section after saving.
  16. Close Keys and Settings blade.

    Make a note of the Application ID on the application details page. In this example it's bbfc1cde-8097-4e7a-bc4e-9cd7969c733c.


Custom Key Identifier

  1. Click the Manifest button which will open the Manifest blade.

    Make a note of the value for "customKeyIdentifier" under the "KeyCredentials" node. If you have multiple certificates uploaded, select the one with the correct "startDate" and "endDate" values.


  2. This step is a temporary workaround due to changes in Azure AD: Convert the customKeyIdentifier hexadecimal value to base64. If you are unsure of how to do that, there are several services online that will do it for you. Search for "hex to base64" or try this one: https://base64.guru/converter/encode/hex.

    Use the base64 encoded customKeyIdentifier value in Evoko Home.

Key/Pem files

You need openssl available on your machine. Please see https://www.openssl.org/ for more information on openssl.

  1. Generate a ~10 years certificate pair. 
    openssl req -x509 -days 3650 -newkey rsa:2048 -keyout cert.key -out cert.pem
  2. Decrypt the private key 
    openssl rsa -check -in cert.key -out cert-plain.key
  3. you can use cert-plain.key for “key” file and cert.pem for “pem” file in the setup wizard.