Introduction

Microsoft Graph is the gateway to data and intelligence in Microsoft 365. It provides a unified programmability model that you can use to access the user-centric data in Microsoft 365. In other words, it is Microsoft’s API that gives access to Microsoft 365 resources. The Cirrus Connect platform uses this API for several purposes to interact with Microsoft 365. To enable this functionality the Cirrus server has to be registered via an application registration in Azure. This document describes the steps required in Azure to enable functionality in the Cirrus server. 

Currently, we distinguish four functions that use the Microsoft Graph API: 

• Active Directory; Used to import users and groups from Azure Active directory into the UCS system.
• Outlook Calendar; Used to retrieve busy/free information of users.
• Outlook mail; Used to send and (optionally) receive E-mails (E-mail routing).
• User Presence; Used to retrieve the (teams) presence state of users. 

Depending on the function that is required certain permissions have to be granted to the Cirrus server. It is recommended that only one app registration is made for the Cirrus server and to give it the permissions required. (If additional functions are added in future, only the new permissions need to be added to the application registration.) 

There are two kinds of permissions that can be used when connecting to the Graph API, namely Application Permission (Application ID and -Secret with rights assigned in the Azure Portal to what can be accessed) and Delegated Permission (The application "impersonates" an Azure User to access certain resources that the user has access to). Each exposed service requires that either Application or Delegated permissions be assigned. If Delegated permission is required an account has to be provided to login.

Create an App Registration

1. Browse to https://portal.azure.com
2. Search for, and select ‘App registrations’.

3. Click ‘New registration’.

4. Fill in the name for the application.
5. Set the supported account types to ‘Accounts in this organizational directory only’.
6. Leave the Redirect URI empty.
7. Press ‘Register’.
8. Now that the application is created, copy the Application (client) ID as this has to be set in the Cirrus Connect platform.

API Permissions

Next we have to give the application the required permissions to read the presence of all users.

1. Click on ‘API Permissions’.
2. Click ‘Add a permission’.
3. Select ‘Microsoft Graph’.

   Service	Type of permission	Permission
   Active Directory	Application permissions	User.Read.All Group.Read.All
   Outlook Calendar	Application permissions	Calendars.Read
   Outlook mail	Delegated permissions	Mail.ReadWrite.Shared Mail.Send.Shared Mail.Send.Shared only allows the logged in user to send emails via mailboxes shared with this user  (in the MS365 exchange configuration), not the mailboxes of everyone in the organization.
   Presence	Application permissions	Presence.ReadWrite.All
   	Delegated permissions	User.Read.All Presence.Read.All

    
4. Now select ‘Delegated permissions’, or ‘Application permissions’, depending on the function configuring. Here we will configure the delegated permission ‘Presence.Read.All’ as an example.
5. Search for ‘presence’.
6. Select ‘Presence.Read.All’.
   1. If using Azure AD sync with the Cirrus server this will be sufficient.
   2. If using (on premise) Active directory sync with UCS also the User.Read.All permission is required.
7. Click ‘Add permissions’.

Authentication

Next we have to configure the Authentication.

1. Click on ‘Authentication’ and ‘Allow public client flows’.

2. Next, click ‘Add a platform’.
3. Select ‘Mobile and desktop applications’.
4. Check the first option and fill in ‘urn:ietf:wg:oauth:2.0:oob’ & http://localhost:8639 as custom redirect URIs.
5. Press ‘Configure’.

Create a secret

Now we have created the application, and have given it the permissions. However, if using an Application 
permission no user can log in, and the application has to authenticate itself. This can be done with a Secret Value (application password). Note that this is only used for application permissions, and not for delegated permission. 

To generate a New client secret

1. Click ‘Certificates and Secrets’
2. Click ‘New client secret’
3. Give it a proper description and press add
4. Copy the Value of the secret, as it won’t be readable once the page is left.

Pass to Cirrus

Now you have the app ready in Azure, Cirrus has to configure the application in the backend of Cirrus Connect. Please send the following to your Cirrus point of contact: 

1. the Application ID
2. secret values 
3. Microsoft tenant name & ID

Conclusion

Now we have completed the application creation and configuration in Azure. As mentioned before a user account has to be used to send and receive emails as well as to retrieve the presence. Make sure that you have available the credentials.

The account is used to log into the Cirrus Console to obtain an access token for sending emails but does not necessarily have to have a mailbox. However, it must have access to the shared mailbox(es) used to monitor or receive emails, from which emails are sent. This can be configured in the MS365 exchange portal.
Because the account is used to log into the Cirrus Console once, and then the refresh tokens are used to run the services, we suggest that there are no sign-in policies. If they want to add the user to a sign-in policy that, for example, requires the user to log in every x days, then they must log in with this user in the console every x days. This is not desirable because it is essentially being used as a service account.