Microsoft Graph and Cirrus Connect

Microsoft Graph is the gateway to data and intelligence in Microsoft 365. It provides a single API that allows applications to securely access user data and services within Microsoft 365.

The Cirrus Connect platform uses Microsoft Graph to interact with Microsoft 365 for several key functions. To enable this, the Cirrus server must be registered in Entra (Microsoft’s identity and access management service). This registration creates an application record that controls how Cirrus Connect connects to Microsoft 365.

Functions Using Microsoft Graph

Cirrus Connect currently uses the Microsoft Graph API for four functions:

1. Active Directory
   • Imports users and groups from Azure Active Directory into Cirrus Connect.
   • Enables Single Sign-On (SSO).
2. Outlook Calendar
   • Retrieves users’ free/busy information for scheduling.
3. Outlook Mail
   • Sends and, if required, receives emails (email routing).
4. User Presence
   • Retrieves Microsoft Teams presence information for users.

App Registration and Permissions

• It is recommended to create one app registration in Entra for the Cirrus server.
• Assign only the permissions required for the functions in use.
• If new features are enabled later, you can update the same registration with additional permissions.

Permission Types

Microsoft Graph supports two permission models. Each service used by Cirrus Connect requires one of these:

Application Permissions

• Access is granted directly to the application.
• Uses an Application ID and Secret.
• Permissions are assigned in the Entra portal.
• Suitable for background services that do not require user interaction.

Delegated Permissions

• The application acts on behalf of a signed-in user.
• Access is limited to the resources that user has permission to use.
• Requires a login account for authentication.

This guide explains the steps required in Entra to configure Cirrus Connect for Microsoft Graph access.

Step 1: Create an App Registration

1. Browse to https://entra.microsoft.com/
2. Click ‘App registrations’
   
3. Click ‘New registration’
   
4. Enter a Name for the application (this can be changed later)
5. Select ‘Accounts in this organizational directory only ({Directory name} only - Single tenant)’ from the Supported account types
6. Leave the Redirect URI (optional) empty for now
7. Click ‘Register’
8. Once the App registration is created, copy the Application (client) ID as this has to be set in the Cirrus Connect platform.

Step 2: Authentication

Next, we have to configure the Authentication. 

1. Click ‘Authentication’
2. Click ‘Add a platform’

3. Select ‘Web’
4. Fill in the Redirect URI: https://<YOUR CIRRUS DOMAIN>/webclient/signin-oidc
5. Press ‘Configure’
6. Now that we have the webclient redirect in place, we can repeat steps 2-4 for the Redirect URI: https://<YOUR CIRRUS DOMAIN>/supervisor/signin-oidc and Redirect URI: https://<YOUR CIRRUS DOMAIN>/administrator/signin-oidc
7. Click 'Add a platform'
8. Click ‘Mobile and desktop applications’
9. Check the first option https://login.microsoftonline.com/common/oauth2/nativeclient under Mobile and desktop applications
10. Click ‘Add URI’ and enter http://localhost:8639 as a custom redirect URI
11. Check both ‘Access tokens (used for implicit flows)’ and ‘ID tokens (used for implicit and hybrid flows)’ under Implicit grant and hybrid flows
12. Toggle ‘Enable the following mobile and desktop flows:’ to Yes under Allow public client flows
     

Step 3: Expose an API

Next, you need to expose an API by creating a scope for the App registrations, which will allow authenticated users to access Cirrus data through the API. 

1. Click ‘Expose an API’
   

   

2. Check the ‘Application ID URI’ is populated - the format must be `api://<Application ID>` where Application ID is the ID generated by Microsoft for this App registration 
    

3. Click ‘Add a scope’
4. Enter ‘Unexus.Access’ as the Scope name
5. Toggle the ‘Who can consent’ slider to ‘Admins and users’
6. Provide a meaningful description to the ‘Admin consent display name’ and ‘Admin consent description’ text fields e.g., Cirrus Connect Access
7. Toggle the ‘State’ slider to ‘Enabled’
8. Click Save

Once the API Scope has been created, you can add this permission under the API permissions menu as a Delegated permission so that it does not ask your users for consent when they log in (see API Permissions below).

1. Click ‘API permissions’
2. Click ‘Add a permission’
3. Click ‘APIs my organisation uses’
4. Type the name of the App registration
5. Click the name of the App registration
6. Once selected, Check the created permission “Unexus.Access” in the Permission table and click Add permission.
7. Click ‘Grant admin consent for <organisation>’ in Configured permissions”

Step 4: API Permissions

Next, we have to grant the application the required permissions.

The table below reflects the API permissions (both Application and Delegated) and the associated function:

1. Click ‘API Permissions’
   
2. Click ‘Add a permission’
3. Click ‘Microsoft Graph’
4. Now select ‘Application permissions’, or ‘Delegated permissions’, depending on the function you are 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 the User.Read.All permission is also required.
7. Click ‘Add permissions’.

Step 5: Certificates & secrets

Now we have created the application and have given it the permissions. However, if using an Application permission no user is needed to 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 permissions. 

1. Click ‘Certificates & secrets’
   

   

2. Click ‘New client secret’ to add a new secret
3. Fill in the required fields, Description and Expires, and click ‘Add’.
4. Copy the secret Value and pass to your Cirrus point of contact.

Step 6: Manifest

Lastly, you need to change the Manifest of the App registrations to support v2 Tokens. This can be done as displayed in the screenshot below.

Step 7: Pass to Cirrus

Now that you have the app registration configured in Entra, Cirrus has to configure the application on the Cirrus Connect Server. Please send the following to your Cirrus point of contact: 

1. The Application ID
2. Secret value 
3. Microsoft Directory/Tenant name & ID

Best Practices for Microsoft Graph Integration

When configuring Microsoft Graph access for Cirrus Connect, consider the following best practices to ensure secure and reliable operation.

1. Account Setup for Delegated Permissions

If Delegated permissions are required (e.g. for email or presence):

• Use a dedicated service account.
• The account does not need its own mailbox but must have access to any shared mailbox(es) used for sending or receiving emails.
• Configure mailbox permissions in the Microsoft 365 Exchange portal.
• Keep credentials securely stored and accessible only to administrators.

2. Token Management

• The account is used once to sign in to the Cirrus Console and generate an access token.
• After this, refresh tokens are used automatically by Cirrus Connect to maintain service access.
• Avoid applying sign-in policies (e.g. forced re-authentication every few days) to this account.
  • Such policies would require repeated manual logins, disrupting service.
  • Since the account operates as a service account, it should not be treated as a standard user login.

3. Permissions Strategy

• Wherever possible, configure a single app registration for the Cirrus server and add permissions as needed.
• If you prefer to separate functionality, create dedicated app registrations for each function.
  • Example:
    • App registration: Cirrus Server – Mail
    • Permissions:
      • Mail.ReadWrite.Shared
      • Mail.Send.Shared

This approach minimises unnecessary permissions and simplifies troubleshooting.