Who is this article for?

This article is for Microsoft 365 administrators and Cirrus Insight admins setting up an admin-managed connection, also called a service account. A service account lets Cirrus Insight sync email and calendar data for many users from a single app registration in Microsoft Entra ID, so each user does not have to sign in and grant consent individually.

If your users connect their own mailboxes instead, see How do I use Manage Connections?

Why does Cirrus Insight need an app registration?

Cirrus Insight reads and writes mailbox data through Microsoft Graph. For an admin-managed connection, Microsoft requires an app registration in your Entra tenant. The app registration gives Cirrus Insight three things:

• An identity (the Application ID and Directory ID)
• A credential (a client secret)
• A set of application permissions that an admin has consented to

You control which Cirrus Insight features can run by choosing which permissions to grant, and you can optionally limit which mailboxes the service account can reach. See Restricting which mailboxes the service account can reach at the end of this article.

Before you start

You will need:

• A Microsoft Entra account with the Global Administrator or Application Administrator role
• Admin access to the Cirrus Insight Admin Dashboard
• About 15 minutes

Step 1: Create the app registration in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center as a Global Administrator or Application Administrator.
2. In the left navigation, under Entra ID, select App registrations, then New registration.
3. Give it a name, such as Cirrus Insight Service Account.
4. Under Supported account types, choose Single tenant only.
5. Leave Redirect URI blank and select Register.
6. On the Overview page, copy these two values. You will paste them into Cirrus Insight in Step 3.
   • Application (client) ID
   • Directory (tenant) ID
7. Go to Certificates & secrets → Client secrets → New client secret. Enter a description and choose an expiry.
8. Copy the Value immediately. It is only shown once.

Keep track of your client secret's expiry

Client secrets expire, with a maximum lifetime of 24 months. When this secret expires, every user synced through the service account stops syncing at once and the service account shows as Disconnected in Cirrus Insight. Record the expiry date somewhere your team will see it, and set a reminder before it lapses.

To rotate the secret, create a new client secret in Entra, open the existing service account in Cirrus Insight, paste the new Value into the Client Secret field, and Save. Users resume syncing on the next cycle.

Cirrus Insight supports client secrets only; certificate credentials are not supported.

Step 2: Add Microsoft Graph permissions

1. In the app registration, go to API permissions → Add a permission → Microsoft Graph → Application permissions.
2. Add only the permissions for the Cirrus Insight features you plan to use (see the table below).
3. Select Add permissions, then Grant admin consent for [your tenant]. Every permission should show a status of Granted.

All permissions must be Application permissions. Delegated permissions have no effect for a service account.

Which permissions to add

Combine rows for the features you use. For example, Email Sync + Calendar Sync needs Mail.ReadWrite, Calendars.ReadWrite, and MailboxSettings.Read.

What each permission does:

• Mail.ReadWrite: read messages and folders, apply the "Filed with CI" category to synced emails, and create drafts for Email Blasts.
• Calendars.ReadWrite: read calendars and events, create and update events for Salesforce → Outlook sync and Calendar Scheduling bookings, and apply the "Filed with CI" category to synced events.
• MailboxSettings.Read: read each user's mailbox time zone so event times are correct.
• Mail.Send: send Email Blasts on the user's behalf.
• User.Read.All: read directory profile attributes (display name and email aliases) so Cirrus Insight can match aliases to the primary address and match sent Email Blasts to Salesforce records. This permission does not grant access to mailbox content.

Do not add Mail.Read alongside Mail.ReadWrite, or Calendars.Read alongside Calendars.ReadWrite. The ReadWrite permission already includes everything Read allows.

Not available through a service account: Task Sync (Cirrus Insight To Do) requires an individual user connection.

Read-only option

If your security policy does not allow write access to mailboxes or calendars, Cirrus Insight can run Email Sync and one-way Calendar Sync (Outlook → Salesforce) with read-only permissions.

Before enabling sync with read-only permissions, make these changes in Cirrus Insight:

1. Click the gear button in the blue navigation blade to open Settings, then click Sync. Make sure you are on the Org Settings tab (admins land there by default).
2. On General Settings, turn off both Add "Filed with CI" label to emails and Add "Filed with CI" label to events.
3. Below each toggle, uncheck Users can modify so users cannot re-enable the setting for their own accounts.
4. Click Calendar Sync, then Rules. Turn on Sync events from email to Salesforce only. Leave Sync events from Salesforce to email off.

Calendar Scheduling and Email Blasts are not available with read-only permissions, since both need to create items in the mailbox.

Step 3: Configure the service account in Cirrus Insight

1. Add your email domains first. Click the gear button to open Settings. In the blue navigation blade on the left, under Administration, click Domains, then Add Domain. Enter each domain as plain text without the @ sign (for example, contoso.com). Users whose domain is not on this list are not picked up by the service account, and no error is shown.
2. Still under Administration, go to Advanced → Authentication → Service Accounts and click + Add.
3. Choose Connect using Office 365.
4. Fill in the form:
   • Client Id: the Application (client) ID from Step 1
   • Client Secret: the secret Value from Step 1
   • Tenant: the Directory (tenant) ID from Step 1
   • Domain List: select the domains this service account covers. Only domains added in step 1 appear here.
   • Test Account (optional): the primary email address of one licensed mailbox in your tenant
5. Optionally select Run Test, then select Save. Saving does not run the test.

The service account now appears in the Service Accounts list with a status of Connected. Connected means Cirrus Insight was able to sign in with your Client Id, Secret, and Tenant. It does not confirm that permissions were granted.

What "Run Test" checks

Run Test signs in with your app registration and reads one day of calendar events from the mailbox in the Test Account field. It confirms your Client Id, Secret, and Tenant are correct and that a Calendars permission has been granted.

Run Test does not check Mail permissions, other mailboxes, or your Domain List.

"Test failed" is expected, and not a problem, when:

• You granted only Mail permissions (an Email Sync-only setup). The test reads a calendar, so it fails. Email Sync is unaffected. Confirm your setup by enabling sync for one user and checking that user's sync status.
• You restricted the service account to specific mailboxes (see below) and the Test Account mailbox is outside that group. Test with a mailbox in the group instead.
• You changed mailbox restrictions in Exchange within the last couple of hours. Exchange can take up to two hours to apply the change.

"Test failed" is a real problem when:

• The Secret ID was pasted instead of the secret Value
• The Tenant ID is wrong
• Admin consent was not granted on the permissions
• The Test Account mailbox is unlicensed or hosted on-premises

If you have checked all of the above and the test still fails, contact Cirrus Insight Support and include the email address the admin who set up the service account uses to sign in to Cirrus Insight.

Restricting which mailboxes the service account can reach

The permissions you grant in Entra ID apply to every mailbox in your tenant. If you want to limit the service account to specific mailboxes (for example, only your sales team), your Exchange Online administrator can do this using Role Based Access Control (RBAC) for Applications in Exchange Online.

Cirrus Insight fully supports RBAC-scoped service accounts. Setup happens entirely on the Microsoft side, so it is not covered in this article. Microsoft's guide is here: Role Based Access Control for Applications in Exchange Online.

A few things to share with your Exchange admin:

• Use the RBAC application roles that match the permissions you added in Step 2 (for example, Application Mail.ReadWrite and Application Calendars.ReadWrite).
• User.Read.All cannot be scoped this way. It is a directory permission, not a mailbox permission, and it only exposes profile attributes, not mailbox content.
• Only users in the scoped group can be synced. If you add a user to Cirrus Insight later and they are not in the group, their sync will fail until they are added.
• Microsoft has replaced the older Application Access Policies with RBAC for Applications. If you have an existing Application Access Policy, your admin should migrate it.

Next steps

Your service account is connected. To start syncing, enable Email Sync or Calendar Sync for your users. See Sync Administration with a Service Account for how to manage users under a service account.