# Connect Microsoft Teams

Canonical URL: https://docs.fuse.init.inc/integrations/microsoft-teams/setup

Register a Microsoft Entra app for delegated Graph access and create a verified Init connection.



## Before you start [#before-you-start]

**Engine operator** registers one Microsoft Entra ID application (platform OAuth app) for Init’s Microsoft Teams pack. **Connection admin/user** signs in and consents (user or admin consent, depending on the Graph permissions requested).

You need:

* Permission to register apps in the operator Entra tenant that owns the platform app.
* A Microsoft 365 user who can consent to Teams/Graph delegated permissions in the customer tenant (or a tenant admin when admin consent is required).
* The engine public base URL for the redirect URI.

## Configure the provider [#configure-the-provider]

### One-time platform Entra app (**Engine operator**) [#one-time-platform-entra-app-engine-operator]

1. In Microsoft Entra admin center, register a new application.

2. Add a Web redirect URI:

   `{FUSE_PUBLIC_URL}/v1/oauth/microsoft_teams/callback`

3. Create a client secret for the confidential web client.

4. Under **API permissions**, add only the Microsoft Graph **delegated** permissions required by the Init Teams actions you expose. Do not add application permissions or unused delegated scopes “just in case.”

5. Copy the Application (client) ID and client secret into the Fuse environment as `MICROSOFT_OAUTH_CLIENT_ID` and `MICROSOFT_OAUTH_CLIENT_SECRET`. Never commit these values.

This Teams app configuration is separate from Microsoft Intune’s `MICROSOFT_INTUNE_OAUTH_*` credentials.

### Per-tenant authorization (**Connection admin/user**) [#per-tenant-authorization-connection-adminuser]

Customers authorize delegated access through Init Connect. They do not paste client secrets into Connect.

## Connect to Init [#connect-to-init]

1. **Connection admin/user** starts a Microsoft Teams Connect session.
2. Sign in with the Microsoft work account that should own the connection.
3. Approve consent for the requested Graph scopes (admin consent may appear for organization-wide permissions).
4. Init completes the authorization-code exchange and stores the connection. No customer credential fields are submitted.

If Init later requests additional Graph scopes for new actions, reconnect so Entra issues an updated refreshable grant.

## Permissions [#permissions]

Action-required Graph scopes appear on the generated scope matrix.

**Baseline identity/consent scopes** (runtime policy, not action-declared): Init also requests `openid`, `profile`, `offline_access`, and `User.Read` so the connection can identify the user and refresh tokens. Treat these as separate from action-required Teams scopes.

Many Teams chat and channel permissions require admin consent in customer tenants. Prefer least privilege and document which actions trigger admin consent before rollout.

## Verify the connection [#verify-the-connection]

1. Confirm Connect completes and Init shows an active Microsoft Teams connection.
2. Run a safe read such as listing teams or chats the signed-in user can access.
3. Success looks like Graph returning data for that user without `InvalidAuthenticationToken` or consent-required errors.

## Rotate or revoke access [#rotate-or-revoke-access]

* **Rotate platform client secret (Engine operator):** create a new Entra client secret, update `MICROSOFT_OAUTH_CLIENT_SECRET`, remove the old secret after cutover.
* **Revoke customer access (Connection admin/user):** revoke the user’s grant in Entra Enterprise applications / Connected apps, or delete the Init connection.
* After permission changes on the Entra app, customers must reconnect (and admins may need to re-grant admin consent).

## Troubleshooting [#troubleshooting]

| Symptom                         | What to check                                                                                            |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `AADSTS50011` redirect mismatch | Redirect URI must exactly match `{FUSE_PUBLIC_URL}/v1/oauth/microsoft_teams/callback`.                   |
| Admin consent required          | Tenant policy blocks user consent for the requested Graph scopes; ask a Global Admin to consent.         |
| `403` on Teams APIs             | Delegated permissions missing or consent not granted for those scopes; reconnect after updating the app. |
| Wrong tenant signed in          | Sign out of Microsoft sessions and reconnect with the intended work account.                             |
| Engine misconfigured            | Confirm `MICROSOFT_OAUTH_CLIENT_ID` / `MICROSOFT_OAUTH_CLIENT_SECRET` (not the Intune-specific vars).    |