Skip to main content

Microsoft 365

Hearth can use a Microsoft 365 business tenant for sign-in and for five connectors: calendar, contacts, mail, files, and chat notifications into Teams. All of them read and write, except chat notifications, which only post. It is meant for a self-hosted Hearth.

Every connector is off until an administrator turns it on. Every connection is one person's own, made with delegated permissions. Hearth works in a person's mailbox, calendar, address book, and drive as that person, and never holds an application permission that reaches a whole tenant.

What each connector does is on Connectors. This page is the setup.

Register the app in Microsoft Entra​

In the Microsoft Entra admin center, under App registrations, make one registration for Hearth.

  1. Supported account types: accounts in this organizational directory only (single tenant), or accounts in any organizational directory if one Hearth serves several tenants.
  2. Redirect URIs, platform Web, both of these exactly, with no trailing slash:
    • https://hearth.example.com/auth/callback for sign-in
    • https://hearth.example.com/integrations/microsoft/callback for the connectors
  3. Under Certificates and secrets, make a client secret and keep its value for your Hearth secret.
  4. Under API permissions, add these as Delegated permissions, and only the ones for the connectors you will turn on:
ConnectorDelegated permission
Sign-inopenid, profile, email, offline_access, User.Read
CalendarCalendars.ReadWrite
ContactsContacts.ReadWrite
MailMail.ReadWrite, Mail.Send
FilesFiles.ReadWrite.All, Sites.Read.All (to find the SharePoint sites a person follows)
Chat notificationsnone

Files.ReadWrite.All, Sites.Read.All, and some tenant policies need an administrator's consent. Grant it once for everybody under API permissions, or from Settings, then Connectors, with Grant for the whole tenant.

Install​

In the chart values:

oidc:
enabled: true
provider: microsoft
microsoftTenant: 00000000-0000-0000-0000-000000000000 # your directory (tenant) ID
clientId: <application (client) ID>
allowedDomains: contoso.com
microsoft:
enabled: true
encryption:
enabled: true

The client secret goes in your existing Hearth secret under OIDC_CLIENT_SECRET and MICROSOFT_CLIENT_SECRET, and the application ID under MICROSOFT_CLIENT_ID. Encryption has to be on, because a refresh token has to be stored and Hearth will not store one in the clear. With Microsoft on and encryption off, Hearth says so at start and leaves the connection off.

Sign-in​

With oidc.provider: microsoft, sign-in goes to your tenant's own authority and Hearth checks the tid claim in the signed token against microsoftTenant. People are matched on their object ID (oid), which survives a rename, and never on their address. Entra sends no email claim unless you add it, so Hearth falls back to preferred_username for the allowed-domain check.

For one Hearth that serves several tenants, set microsoftTenant: organizations and list the directory IDs in microsoftAllowedTenants. Left empty, any work or school account may sign in, and Hearth logs that at start. Each token's issuer is checked against its own tenant.

Groups to roles​

oidc.roleMap gives a Hearth capability to anybody whose token carries a group or app role:

oidc:
roleMap: "5f0e2c1a-1111-4b6e-9d3f-aaaaaaaaaaaa=audit,Finance-Team=finance"

In your app registration, under Token configuration, add the groups claim (security groups), or define app roles and assign them. A group is named by its object ID in the token, and an app role by its value. The capabilities are people, agents, audit, finance, and time_all. super_admin cannot be given this way, and the account that claimed the installation is never changed. Losing the group takes the capability back at the next sign-in, and a capability somebody granted by hand in Hearth is never taken back.

An account in more than 200 groups gets a pointer in its token instead of the list. Hearth then asks Microsoft Graph for the list as that person, which is why sign-in asks for User.Read. If Graph will not answer, that sign-in fails rather than carry on as if the person had no groups.

Turn the connectors on​

  1. Sign in as the owner or a super admin and open Settings, then Connectors.
  2. Under Microsoft 365, enter the directory (tenant) ID and choose Connect. Only accounts in that tenant can connect.
  3. Turn on the connectors you want.
  4. Each person opens the same page, chooses Connect my Microsoft 365 account, and ticks what they want. They see what Microsoft asks before anything is granted.

The connectors pull from Microsoft every ten minutes. Set connectors.interval in the chart to change it, down to one minute.

A Teams link is added to an event Hearth creates only when the person's calendar allows Teams meetings. If Teams is not provisioned for them, Outlook ignores the request and the event is created without a link. To check, ask Graph for /me/calendar?$select=allowedOnlineMeetingProviders: it has to include teamsForBusiness.

Check it on your own tenant​

Run this once on yours before you rely on it:

  1. Sign in with a Microsoft account in the tenant. Expect to land signed in, with the account named as in Entra.
  2. Connect from Settings, then Connectors with the calendar ticked. Expect a Microsoft consent screen listing Calendars.ReadWrite.
  3. Make an event in Outlook for tomorrow and choose Sync now. Expect it on the Hearth calendar.
  4. Make an event in Hearth and sync. Expect it in Outlook.
  5. Open Mailbox. Expect your inbox, open a message with its whole body, reply, and expect the reply in Outlook's Sent Items.
  6. Make a contact in the CRM and sync. Expect it in your Outlook contacts, and the reverse.
  7. Open Cloud files, upload a file, rename it, move it, and delete it, and expect each in OneDrive.
  8. Disconnect. Expect the Connectors page to show you as not connected.

If a step fails, the Connectors page shows the last error for each connector and each person, in words.