API connectors (M365, Google, Exchange)

API connectors link an organization's mail platform to Obsidian Email Security for user sync, sign-in with work accounts, clawback of delivered threats, and API-mode scanning. Add one on the organization page.

Capabilities (every connector)

Connector enabled: Master switch.
Sync users and aliases every 4 hours: Creates a user for every mailbox in the organization's domains, keeps display names and aliases current, and disables users removed from the directory. Users that already exist in another organization, and administrators, are left alone. Sync users runs it now.
Allow clawback of delivered threats: Lets administrators (Claw back button) and async-mode AI reviews move delivered messages out of mailboxes.
API mode: Every 2 minutes, new inbox mail in the scanned mailboxes is read, scanned and acted on inside the mailbox: quarantine-worthy mail is moved out (restorable with Release), tagged spam is moved to Junk. Scan mailboxes runs it now. The first run only records a starting point - it does not rescan old mail.
Show Microsoft 365's own quarantine here: (Microsoft 365, organizations whose platform is Microsoft 365; on by default.) Every 5 minutes the mail Microsoft's own filtering quarantined in the tenant is read and listed in Quarantine, the user portal, digests and the mail apps, marked Microsoft 365 quarantine. Release and Delete act in Microsoft: Microsoft delivers a released message itself; a message deleted for all its recipients is deleted there too. Released or deleted in Microsoft (Defender portal, a user's own release, expiry) shows here within 5 minutes. Spam and bulk can be released by users as the policy allows; phishing, malware and mail-flow-rule items stay admin-only. These messages are not scanned again and are not counted on the dashboard. Needs the extra Exchange Online permission below. Pull Microsoft quarantine runs it now; the connector page shows the last result.
Let users sign in: (Microsoft 365 / Google.) Adds "Continue with Microsoft / Google" to the sign-in page. The person must already exist as a user in Obsidian Email Security (sync takes care of that).

Secret fields show stored when a value is saved; leave them blank to keep the stored value. Secrets are encrypted at rest and never shown again. Test connection checks credentials and shows what it found; the result is also kept as the connector's status. Remove connector deletes it and its credentials.

Microsoft 365

Tenant idtenant_id: Directory (tenant) ID GUID from Entra ID > Overview, or the tenant's onmicrosoft.com name.
Client idclient_id: Application (client) ID of the app registration you created for Obsidian Email Security.
Client secretclient_secret: A client secret from the app registration (Certificates & secrets). Stored encrypted; secrets expire - note the expiry date and rotate before it.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user in the organization.
Quarantine folderquarantine_folder: Where clawback moves messages: recoverableitemsdeletions (hidden from the user, recoverable by admins - default), deleteditems, or junkemail.
Quarantine daysquarantine_days: How many days of Microsoft's own quarantine are read when 'Show Microsoft 365's own quarantine here' is on (1-30, default 15 - Microsoft keeps quarantined mail 15 days unless the anti-spam policy says up to 30).
Sso tenantsso_tenant: Tenant used for 'Continue with Microsoft' sign-in. Empty = 'organizations' (any work account; users must still exist in Obsidian Email Security).

Creating the app registration

Entra admin center › App registrations › New registration, name "Obsidian Email Security", single tenant.
API permissions › Microsoft Graph › Application permissions: User.Read.All and Mail.ReadWrite › Grant admin consent.
Certificates & secrets › New client secret; copy the value (shown once) into client_secret. Note the expiry.
Copy the Directory (tenant) ID and Application (client) ID into the connector.
For sign-in: Authentication › Add a platform › Web › redirect URI <console URL>/auth/oidc/m365/callback, and delegated permissions openid, email, profile.
Least privilege (optional): restrict Mail.ReadWrite to the scanned mailboxes with an Exchange Online RBAC for Applications scope.
Microsoft's own quarantine: API permissions › Add a permission › APIs my organization uses › Office 365 Exchange Online › Application permissions: Exchange.ManageAsApp › Grant admin consent. Then Entra › Roles and administrators › Security Administrator › Add assignments › the app. (Security Reader can list the quarantine but not release or delete.) Without them the connector page shows a 401/403 from Exchange Online.

Google Workspace

Admin emailadmin_email: A Google Workspace super admin the service account impersonates for directory reads.
Customercustomer: Customer ID for directory queries; my_customer (default) means the admin's own account.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user.
Service account jsonservice_account_json: The whole JSON key file of the service account (paste the contents). Stored encrypted.
Oauth client idoauth_client_id: Client ID of a Google OAuth 'Web application' client, used only for 'Continue with Google' sign-in.
Oauth client secretoauth_client_secret: Secret of that OAuth client. Stored encrypted.

Creating the service account

Google Cloud console: create a project; enable the Gmail API and Admin SDK API.
IAM › Service accounts › create one, then Keys › Add key › JSON. Paste the file's contents into service_account_json.
Google Admin console › Security › Access and data control › API controls › Domain-wide delegation › Add new: the service account's client ID with the scopes
https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/gmail.modify
For sign-in: APIs & Services › Credentials › Create OAuth client ID (Web application) with redirect URI <console URL>/auth/oidc/google/callback; paste its ID and secret.

Clawback in Google moves the message to Trash; restore untrashes it and puts it back in the inbox.

Exchange (on-premises)

Ews urlews_url: Exchange Web Services endpoint, normally https://mail.<domain>/EWS/Exchange.asmx.
Ews usernameews_username: Service account with the ApplicationImpersonation role (DOMAIN\user or user@domain).
Ews passwordews_password: That account's password. Stored encrypted.
Ews authews_auth: NTLM (default, what Exchange expects) or basic.
Verify tlsverify_tls: yes / no. Choose no only when Exchange uses an internal CA the gateway does not trust.
Ldap urlldap_url: Domain controller for directory sync and user sign-in, e.g. ldaps://dc1.contoso.local:636.
Ldap bind dnldap_bind_dn: Account used to read users (can be the same service account).
Ldap passwordldap_password: Its password. Stored encrypted.
Ldap base dnldap_base_dn: Search base, e.g. DC=contoso,DC=local.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user.

Preparing Exchange

Create a service account, e.g. svc-obsidian.
In the Exchange Management Shell: New-ManagementRoleAssignment -Name ObsidianImpersonation -Role ApplicationImpersonation -User svc-obsidian
EWS URL is normally https://mail.<domain>/EWS/Exchange.asmx; keep NTLM authentication.
LDAP: use LDAPS (port 636) to a domain controller. The same account can bind for directory reads.

Users of an Exchange organization sign in to the portal with their Windows password (checked against the domain controller) - no password is stored in Obsidian Email Security.

Obsidian Mail Server

Server urlserver_url: The Mail Server's address, e.g. https://mail.contoso.com - shown next to the key on the Mail Server's Email Security page.
Connect addressconnect_address: Optional. The Mail Server's IP address when its name points somewhere else from the gateway (for example the public address the firewall cannot loop back to). The name is still used for the TLS certificate.
Verify tlsverify_tls: yes / no. Choose no only when the Mail Server uses a certificate the gateway does not trust (self-signed, internal CA).
Api keyapi_key: A connector key (omsk_...) made in the Mail Server's admin center: Mail > Email Security > Connector for Email Security. It works for that one organization. Stored encrypted.
Mailboxesmailboxes: Mailboxes scanned in API mode, comma separated. Empty = every active synced user.

Preparing the Mail Server

In the Mail Server's admin center: Mail › Email Security › Connector for Email Security › Create key. It shows the server address and the key once; paste both here.
On the same page, under Spam filing, add the address this gateway delivers from. The Mail Server then trusts the X-Obsidian headers only from the gateway and puts X-Obsidian-Spam: Yes mail in Junk Email by itself.
Test connection shows the Mail Server's version, the organization and how many recipients it has; then Sync users.

Sync brings in mailboxes, shared mailboxes, rooms, groups and mail-enabled public folders with all their addresses, so recipient checks accept every real address. People sign in to the portal with their Mail Server password (which can be their Windows password when the Mail Server syncs Active Directory) - no password is stored in Obsidian Email Security. Clawback moves a message to the mailbox's Recoverable Items (hidden from the person); restore puts it back in the folder it came from.

Moving from Exchange to the Mail Server: remove (or switch off) the old Exchange connector, then Sync users here. People synced from Active Directory then sign in with their Mail Server password; while an enabled Exchange connector remains, they keep signing in through it.

Status and errors

The connector page header shows the last activity and result (test, sync or poll). Background failures also appear under System health › Background jobs. Common causes: expired client secret (M365), missing admin consent, delegation scopes typed wrong (Google), the service account lacking impersonation rights (Exchange).