Microsoft 365 Connector

Get Microsoft 365 credentials

Register an app in Microsoft Entra ID (Azure AD) and grant Microsoft Graph permissions. You need three values: Tenant ID, App (Client) ID, App (Client) Secret. This app is also reused by the Teams channel.

1. Register the app

1. Azure Portal → Microsoft Entra ID → App registrations → New registration → name it → Register.
2. Overview → copy Directory (tenant) ID → field Azure AD Tenant ID.
3. Overview → copy Application (client) ID → field App (Client) ID.

2. Client secret

Certificates & secrets → New client secret → copy the Value immediately (not shown again) → field App (Client) Secret.

3. Graph permissions

1. API permissions → Add a permission → Microsoft Graph → Application permissions.
2. Add what your use case needs (e.g. Calendars.Read, Mail.Read, User.Read.All, Files.Read.All).
3. Click Grant admin consent for <Tenant> (requires an admin).

For the Teams provisioning capability (teamsProvisioner@1) additionally add: Application.ReadWrite.OwnedBy, AppCatalog.ReadWrite.All, TeamsAppInstallation.ReadWriteForTeam.All, TeamsAppInstallation.ReadWriteAndConsentForTeam.All, Team.ReadBasic.All.

To install an agent into a group chat (since 0.7.0) also add TeamsAppInstallation.ReadWriteForChat.All and TeamsAppInstallation.ReadWriteAndConsentForChat.All. Not the …SelfForChat.All variant — that one only lets an app install itself, while the provisioner installs the per-agent app it generated.

The two …AndConsent… roles are not optional extras: the generated app packages declare seven resource-specific permissions, and an install that cannot consent to them is refused with 400 ResourceSpecificPermissionsMismatch (since 0.8.2 the connector sends the consent itself — the role is the half you grant).

Listing the teams an agent can be installed into (listTeams, since 0.8.0) needs no new permission: it reuses Team.ReadBasic.All from the list above. Listing CHATS is a different story — see the note at the end of the sign-in section below.

4. One-time admin sign-in for catalog publishing

Publishing a Teams app package (POST /appCatalogs/teamsApps) is the one step Microsoft Graph does not support with application permissions — the reference says "Not supported." for that verb. omadia therefore asks a tenant administrator to sign in once per tenant. Every agent provisioned afterwards publishes automatically; there is no manual upload per agent.

omadia registers a minimal helper app for this itself (public client, no client secret, one delegated permission: AppCatalog.ReadWrite.All). Start the sign-in from the omadia UI, open the shown URL, enter the code, and approve for your organization. If the sign-in page says approval is required, an admin must first open the consent link omadia displays.

Note: if your tenant blocks the OAuth device code flow via Conditional Access ("authentication flows"), the sign-in fails. Add an exception for the omadia publisher app — it holds two delegated permissions and no secret.

One more sign-in as of 0.8.0

The sign-in now also asks for the delegated Chat.ReadBasic, so omadia can OFFER the administrator's chats as install targets instead of asking an operator to paste a chat id. Microsoft Graph has no tenant-wide application-permission route for listing chats at all — bare GET /chats is delegated-only and the application form is the per-user GET /users/{id}/chats — so this is the only way to build the list.

Chat.ReadBasic reads names and members of chats, never messages, and needs no admin consent of its own. But an existing credential cannot acquire it by refreshing: an administrator who signed in before 0.8.0 has to sign in once more before the chat picker works. Publishing keeps working with the old credential in the meantime; only the chat list reports the gap, and it reports it as a typed "sign in again" rather than a permission error.

Extending an existing app registration requires renewed admin consent: click Grant admin consent for <Tenant> again. If Graph still answers 403 afterwards, grant the app roles via REST appRoleAssignments and restart the middleware — portal/CLI consent sometimes silently fails to apply.

App-only (client-credentials) flow: no user sign-in, access is tenant-wide within the granted permissions.