Step 1 - Configure the Outlook add-in in Microsoft Entra

Configuring the Outlook Add-in in Microsoft Entra

To enable the Outlook add-in, you need to configure additional settings in the Humly Control Panel Application.

Authentication

1. In Microsoft Entra, in the left menu go to App registrations and click All applications.

2. Search and find your application that was registered for Humly Control Panel.
   Note: If you don’t have an Humly Control Panel application configured, follow this guide to create the application with Single Sign-On Booking System Preparations - M365, and continue from here afterwards.
   
   
   

3. Click on your application.

4. Go to Authentication (Preview), click Add Redirect URI → Web under web applications.
   
   
   

5. In Configure Web, for Redirect URIs enter the URI for your Humly Control Panel, and click Configure.
   Note: Must include https:// followed by the domain and /auth e.g. https://xxxxx.humly.cloud/auth where x is your cloud ID.
   
   
   1. URI Syntax (Humly Cloud (replace xxxxx with your cloud ID)):
      
      https://xxxxx.humly.cloud/auth
      
      
   2. URI Syntax (on-prem, local or self-hosting server):
      
      https://yourdomain.com:3002/auth
      
      

API Permissions

1. Go to API permissions in your application, then click Add a permission → Microsoft Graph.
   

2. For Microsoft Graph select Delegated permissions.
   

    

3. Search for and select the following permissions, and then add them.

   1. Calendars.ReadWrite - Needed to fetch event details, create or update calendar events, and synchronize changes with backend APIs. Covers all calendar read and write operations.

   2. User.Read - Enables user authentication and identity verification. Required for login and token generation.

   3. offline_access - Allows the app to use refresh tokens so the user doesn’t need to reauthenticate frequently. Essential for long-running add-in sessions.

   4. openid - Enables secure authentication using Microsoft identity platform. Required for modern OAuth 2.0 sign-in flows.

   5. profile - Grants access to basic user information (e.g. name, preferred username) for personalization in the add-in user interface.

   6. email - Required to associate calendar events with a user’s email. Useful for logging backend correlation, and displaying event ownership information.
      
      

4. In API permissions, you should now have something like this.
   Important! Make sure you click Grant admin consent for… , so each API permission is granted, even the delegated permissions or else the add-in will not allow you to create an event with invited visitors.
   

    

Expose an API

Under Expose an API we will need to add an application ID URI, scopes and a Client ID. Follow the below steps

Application ID URI

1. Go to Expose an API in your application, and for Application ID URI click Add.
   

    

2. The application will provide the Application (client) ID to the API path, but for the outlook add-in to work we will need to modify the path using below syntax as a reference.
   
   a. Application ID URI syntax for Humly Cloud (replace xxxxx with your cloud ID and yyyy with the Application (client) ID).
   
   api://xxxxx.humly.cloud/yyyyy
   
   b. Application ID URI syntax for on-prem, local or self-hosting server installations (replace yyyyy with the Application (client) ID).
   
   api://yourdomain.com:3002/yyyyy
   
   

3. When the Application ID URI has been provided, click Save to add it.
   

    

Scopes defined by this API

1. Under Scopes defined by this API click Add a scope.

2. 4 custom scopes needs to be defined one by one, so let’s start with the first one, and click Add scope for each custom scope
   Note: Scope name, Admin consent display name and Admin consent description are required input fields):

   1. Scope name*: User.Read
      Who can consent?: Admins and users
      Admin consent display name*: User.Read
      Admin consent description*: Standard Microsoft Graph permission used to identify and authenticate the current user.
      User consent display name: User.Read
      User consent description: Standard Microsoft Graph permission used to identify and authenticate the current user.
      
      
      
   2. Scope name*: access_as_user
      Who can consent?: Admins and users
      Admin consent display name*: access_as_user
      Admin consent description*: Allows the add-in to act on behalf of the signed-in user when making API calls. Used to securely exchange user context and perform delegated operations.
      User consent display name: access_as_user
      User consent description: Allows the add-in to act on behalf of the signed-in user when making API calls. Used to securely exchange user context and perform delegated operations.
   3. Scope name*: profile
      Who can consent?: Admins and users
      Admin consent display name*: profile
      Admin consent description*: Grants access to user-specific profile information when interacting with the backend API.
      User consent display name: profile
      User consent description: Grants access to user-specific profile information when interacting with the backend API.
   4. Scope name*: openid
      Who can consent?: Admins and users
      Admin consent display name*: openid
      Admin consent description*: Enables secure authentication and identification of the signed-in user.
      User consent display name: openid
      User consent description: Enables secure authentication and identification of the signed-in user.
3. When having added the necessary scopes you will have a list summarizing them under Scopes defined by this API.
   

Authorized client applications

1. Under Authorized client applications, click Add and enter the following Client ID which represents all Microsoft Office application endpoints.
   
   ea5a67f6-b6f3-4338-b240-c655ddc3cc8e

2. Select all four authorized scopes, and click Add application.
   
3. With that we have everything needed for the add-in under Expose an API.