Registering the XQi Engine in Microsoft 365 to use MS Graph API

The XQi Engine is able to leverage the functions provided in the MS Graph API, which is the API to access all information in Microsoft 365. It allows you to get/update/delete everything your Microsoft 365 tenant, as well as getting notifications (via webhooks), and this is a way to build for example an MS Teams bot, or post messages to team channels, get access to outlook calendars and alike.

Access to the MS Graph API

Of course, this cannot just be done by any application at any time; the necessary security measures are taken. Applications using the MS Graph API can access the tenant in different ways, but, in general can be split up in two different approaches:

  • Connect as a user: The application will let a user sign in, give consent for certain permissions, and will then perform actions in the context of that user, with the permissions set for that user. This is typically used in case the application has a user front-end.
  • Connect as an application: The application has it’s own client ID and accompanying secret, and permissions are set for the application (by the Microsoft 365 administrator). This is primarily used for applications that run as a windows service or deamon and perform certain management or integration tasks (back-end application).

The engine will connect as an application, not as a user.

Every application that accesses the Microsoft 365 tenant must be registered in the Azure Active Directory, where the client ID and secret can be set and the permissions can be given.

Step-by-step registration

For obvious reasons, registering an application can only be done by a Micrososft 365 “Administrator” (someone with a role/profile that can manage applications). If you do not have these permissions, you’ll have to check with your IT admin.

Note: If you are testing, experimenting, or learning, there is the option to create a Microsoft 365 Developer account for free, which gives you a Micrososft 365 tenant where you can play as much as you want (and you will be the administrator). This is a good solution for testing and avoids you have to work in a production environment. More information can be found here: https://developer.microsoft.com/en-us/microsoft-365/dev-program. Important, the developer tenant does not allow to create phone system licenses and other resource licenses related to the Microsoft Phone System, and, as such cannot be used to create every type of application (such as voice bots, for which you will need a real, licensed tenant)

To register an application go to your office portal and go to the admin section. In the admin menu expand all admin centers and select the “Azure Active Directory” menu item.

In the AAD admin center, click the enterprise applications menu item and add a new application.

Select an “Application you’re developing” option, which will bring you to the app registration section of AAD.

Select the option to create a new registration.

Enter a meaningfull name for your registration (e.g. XQi Engine) and select the supported account type. In general, the default setting is ok. You do not have to set a redirect URI for this application (since there is no user login involved). Click the registere button to confirm and to go to the overview screen of the registered application, where we can set all necessary configuration.

In the overview are already two properties we will need to provide in the configuration of the msGraph module of the XQi Engine configuration

  • The application (client) ID
  • The directory (tenant) ID

Make sure to have this available when you configure the engine. Notice there is also a link called “Endpoints” available in the screen. Though the endpoints are quite standard and the same for all apps, it might be good to check these values and see whether they are correct when we configure the engine later on.

Next task is to set the secret for this application. Click the “certificates & secrets” menu item.

Give a description for this key (multiple can be generated) and set a certain expiration date. Click the Add button to add the key.

IMPORTANT: the key will be displayed in the Client secrets list now, but, it will be displayed only once, and cannot be visualized later on! Make sure to copy the key to the XQi Engine configuration or some other file where you can find it later.

Next we’ll configure the access to the (MS Graph) API(s).

Click the menu item “API permissions” for your registration and select the option to add a permission. In the panel that pops up on the right side of the screen, click Microsoft Graph.

Click the “Application permissions” button on top and select one ore more permissions that you need. These permissions depend on what your application will do, and it makes no sense to select all of them. Read the next chapter on how to determine which permissions you need. After selecting one or more permissions, click the add permissions button.

The list of permissions of your registration is now shown, but, you’ll notic that they are not yet granted. The reason for this extra step is that maybe you have the permissions to create an application registration, but, maybe you are not entitled to grant all these permissions to your application (which could create a way to access/modify that that you do not have permission for, but then can go via an application). So either you or the administrator has to grant these permission for the application. After granting the permissions, your registration is ready to use!

Selecting permissions

The MS Graph API is quite big and controlled by many different permissions. So if you are registering the engine, you might wonder which permissions you need to set for the engine’s registration in order to access the data that you need.

Luckily, the API is documented quite well, and, for each API function it lists whether or not it can be called by an application (or must be called in a user context), and, which permission is needed then. The API reference can be found at https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0. You can select a function, for example to get the calendar information.

The function, in this case “List calendars”, can be called by an Application and must have at least one, or both of the mentioned permissions set for the application to be able to execute it. Note that many function will not contain any permission whatsoever for the application part, which means it can only be executed in the context of a particular user.