Obsidian SuiteDocumentation
Obsidian Suite: all chapters

Docs / Obsidian Suite / Connect your mail

Microsoft 365

How to put Obsidian Suite in front of Microsoft 365 / Exchange Online, and how to connect it through Microsoft Graph. Your domain page in the portal (Manage > Organizations > your organization > the domain) shows the same steps, filled in with your domain and Obsidian Suite's addresses.

Before you start

  • Your organization's Platform is Microsoft 365 (organization page, Settings).
  • Your domain is added. Its Deliver clean mail to is your tenant's own MX host, <your-domain-with-dashes>.mail.protection.outlook.com (for contoso.com: contoso-com.mail.protection.outlook.com). This is filled in for you when the domain is added.
  • Note the Obsidian Suite IP addresses listed in step 1 of the domain page's Set up mail flow card. You need them below.

Mail flow

  1. Inbound connector. Exchange admin center > Mail flow > Connectors > Add a connector: from Partner organization to Office 365. Identify the partner by sender IP address, using the Obsidian Suite addresses from your domain page, and require TLS. This makes Microsoft accept mail from Obsidian Suite.
  2. Enhanced Filtering for Connectors. On that connector, turn on Enhanced Filtering with Skip these IP addresses set to the same Obsidian Suite addresses. Microsoft then evaluates the original sender instead of counting Obsidian Suite as the source.
  3. Junk rule. Exchange admin center > Mail flow > Rules: a new rule where A message header matches X-Obsidian-Spam = Yes, with the action Modify the message properties > set the spam confidence level (SCL) to 6. Tagged mail then goes to Junk.
  4. MX record. Change your domain's MX to 10 mx1.obsidiansuite.net. Obsidian Suite delivers clean mail on to your tenant. See Getting started.
  5. Lock down the tenant (after the switch). Add a rule that rejects inbound mail which did not arrive through the connector, so attackers cannot bypass the MX by sending straight to your mail.protection.outlook.com host.
  6. Outbound (optional). See Sending outbound mail.

API connector

The connector adds user sync, sign-in with Microsoft accounts, clawback of delivered threats and, if you want it, API-mode scanning. On your organization page choose API connectors > Add connector > Microsoft 365.

Create the app registration

  1. Microsoft Entra admin center > App registrations > New registration, name it "Obsidian Suite", single tenant.
  2. API permissions > Microsoft Graph > Application permissions: User.Read.All and Mail.ReadWrite, then Grant admin consent.
  3. Certificates & secrets > New client secret. Copy the value (it is shown once) and note the expiry date.
  4. Copy the Directory (tenant) ID and Application (client) ID.
  5. For sign-in with Microsoft accounts: Authentication > Add a platform > Web, redirect URI https://portal.obsidiansuite.net/auth/oidc/m365/callback, and the delegated permissions openid, email and profile.
  6. Least privilege (optional): restrict Mail.ReadWrite to the scanned mailboxes with an Exchange Online RBAC for Applications scope.

Connector fields

FieldWhat to enter
Tenant IDDirectory (tenant) ID from Entra ID > Overview, or the tenant's onmicrosoft.com name.
Application (client) IDApplication (client) ID of the app registration.
Client secretThe client secret. Stored encrypted. Secrets expire: note the date and replace it before then.
Mailboxes to scan (API mode)Comma separated. Empty means every active synced user in your organization.
Clawback destinationWhere clawback moves messages: recoverableitemsdeletions (hidden from the user, recoverable by admins; the default), deleteditems or junkemail.
SSO tenantTenant used for Continue with Microsoft sign-in. Empty means any work account; the person must still exist as a user in Obsidian Suite.

Secret fields show stored once a value is saved. Leave them blank to keep the stored value; secrets are encrypted and never shown again.

Then choose the capabilities, described in API connectors, and use Test connection.

Troubleshooting

  • 401 / invalid_client: the client secret expired or is wrong. Create a new one and paste it into the connector.
  • 403: admin consent was not granted for Mail.ReadWrite or User.Read.All.
  • Mail shows as delivered in Message trace but is not in the mailbox: check that the inbound connector's IP restriction includes every Obsidian Suite address from the domain page, and run Test delivery host on the domain.