Microsoft 365 setup

This guide is for the Microsoft 365 administrator connecting your organization to Connect The Dots. You start from a setup link CTD emails you, and the whole process takes about 5 minutes of your time.

CTD connects through one Microsoft app, CTD Connector. The app holds no mailbox permission of its own: your Exchange admin grants it only the access you choose in the setup, and can remove any of it later.

Who does this: a Global Administrator can do every step alone. Otherwise, a Privileged Role Administrator approves CTD Connector and an Exchange Administrator grants the mailbox access. The setup pages tell you which step needs whom, and you can pass the link between you.

In the setup wizard

Open your setup link and sign in to CTD. The link from CTD’s email (subject “Set up CTD for [your company]”) opens CTD’s sign-in page. Sign in with Google or Microsoft, and the setup wizard opens right after.
Choose Microsoft and what CTD may access. Pick your read level (metadata-only or read-only), whether CTD may send email on your users’ behalf (highly recommended), and whether to sync contacts and calendars. Every change saves on its own, so you can leave and come back with the same link.
Enter your Microsoft 365 admin’s email, then select Create the Microsoft link. This is the person who approves CTD in Microsoft. CTD checks the access on their mailbox, so it must be a real mailbox in your organization.
Continue yourself, or send the link. If you are the Microsoft 365 admin, select I am the Microsoft 365 admin, continue here. Otherwise select Copy link and send it to your admin; you can fill in the rest of the setup meanwhile.

On the Connect Microsoft page

Approve CTD Connector (Global Administrator or Privileged Role Administrator). The page lists exactly what CTD will read. Select Approve in Microsoft, pick your account, and Microsoft opens Permissions requested: Review for your organization for CTD Connector, published by Connect The Dots, Inc. with the verified-publisher badge. It asks to read and write Exchange Online RBAC configuration, sign in and read user profiles, read organization information, and read all users’ full profiles. No mail, contacts or calendar permission appears here; those come in the next step. Select Accept, and the page confirms the approval by itself.
Run the PowerShell block (Exchange Administrator or Global Administrator). The page shows the Exchange roles CTD Connector will get, one per access you chose, and a PowerShell block that grants them. Select Copy on the block, paste it all at once into PowerShell 7 or Windows PowerShell 5.1, wait until it finishes, then select I’ve run it. If someone else is your Exchange admin, select Send this step to your Exchange admin instead.
If your Exchange admin is running the PowerShell, don’t select I’ve run it yourself; leave it for them. Selecting it hides the commands, so they’d have nothing to run. If Exchange refuses a role at first, wait a few minutes and run the New-ManagementRoleAssignment lines again: Microsoft can take a while to apply the first step. To limit CTD to one group, read Limit CTD to a group before running anything.
CTD checks the access. The page shows Verifying: Microsoft takes 30 minutes to 2 hours to apply the roles. You can close the page or select Back to your CTD setup. When CTD has confirmed the access, the page says Microsoft is connected.

Back in the setup wizard

Finish the setup. Add the people who should use CTD (type, paste, or upload a .csv or .txt file), add at least one CTD admin, and pick your CRM. Every change saves on its own.
Select Done. For Microsoft, the Authorize sync step completes by itself once your admin’s part is done, so there is nothing to switch on. You can select Done while CTD is still checking the access: CTD creates the accounts as soon as Microsoft confirms it, and emails you when your workspace is ready.

What each choice grants

Each access you tick in the wizard becomes one Exchange role for CTD Connector, and nothing more:

You ticked	Exchange role	What CTD can do with it
Email metadata	`Application Mail.ReadBasic`	Read sender, recipients, subject, dates and headers; no body, no attachments
Email content	`Application Mail.Read`	Read whole messages, including bodies and attachments
Send email	`Application Mail.Send`	Send mail as a user, only when they ask CTD to
Contacts	`Application Contacts.Read`	Read users’ saved contacts
Calendar	`Application Calendars.Read`	Read users’ calendars and events

Microsoft’s documentation: RBAC for Applications in Exchange Online and grant tenant-wide admin consent.

Limit CTD to a group

CTD can be limited to the direct members of one mail-enabled security group or distribution group (not a dynamic distribution group; members of nested groups don’t count). The setup page doesn’t offer this yet, so the Exchange admin does it by hand at step 6: run the block’s first lines (Connect-ExchangeOnline, the IsDehydrated line and New-ServicePrincipal), skip its New-ManagementRoleAssignment lines (they grant the whole organization), and run this instead, with the ObjectId from the block, your group’s email, and the roles the page lists:

$oid = '<the -ObjectId value from the block>'
$dn = (Get-Group -Identity '<group email>').DistinguishedName
New-ManagementScope -Name 'CTD Connector' -RecipientRestrictionFilter "MemberOfGroup -eq '$dn'" | Out-Null
foreach ($r in 'Application Mail.Read','Application Mail.Send','Application Contacts.Read','Application Calendars.Read') {
  New-ManagementRoleAssignment -Name "CTD Connector - $r" -App $oid -Role $r -CustomResourceScope 'CTD Connector' | Out-Null
}
Test-ServicePrincipalAuthorization -Identity $oid -Resource '<a mailbox in the group>' | Format-Table RoleName,InScope

Every role should show InScope True for a group member and False for anyone outside the group. The admin named in the setup wizard must be in the group, because CTD checks the access on that mailbox. People added to the group later get access within about 2 hours.

Narrowing after the fact: if CTD was granted the whole organization first and limited to a group afterwards, Microsoft keeps honoring the old, wider access for a while (in our testing, about an hour and a half) before CTD stops syncing mailboxes outside the group.

When people join, leave, or lose their mailbox

Nothing to run in Exchange: the roles cover your organization (or the group), not named people.

In your organization	What you do	What CTD does
A new person joins	Nothing; if CTD is limited to a group, add them to it	Finds them within about 3 hours; your CTD admin gives them a seat
A person leaves and their account is deleted	Nothing	Frees their seat
A person loses their mailbox (license removed, mailbox disabled)	Nothing	Stops syncing that mailbox; resumes if it comes back
One of CTD Connector’s roles is removed	Tell CTD first	That capability stops within about 2 hours

Already connected and want to add Contacts or Calendar?

If your organization connected Microsoft 365 before Contacts and Calendar sync were available, or you want to add or remove any capability later, contact cs@ctd.ai or your CTD Account Executive first. We’ll send you the right link and steps for your workspace.

We also see an app called CTD.ai in our tenant. What is it?

That app is behind “Sign in with Microsoft” on CTD’s sign-in page and in the CTD mobile app. Keep it.

How do we remove CTD later?

Remove CTD Connector’s roles in Exchange Online PowerShell:

Get-ManagementRoleAssignment | Where-Object Name -like 'CTD Connector - *' | Remove-ManagementRoleAssignment

Then delete CTD Connector under Microsoft Entra ID → Enterprise applications. CTD loses access to your organization’s mailboxes.

Who do we contact with questions?

Reply to your setup email or write to cs@ctd.ai.