AutoGPT/docs/engineering/microsoft-local-e2e.md

Microsoft connection and sign-in

One Entra app per environment does everything Microsoft: the Teams bot, the Microsoft 365 Copilot chat route, mail/calendar/files/Teams access for Otto and workflows, Work IQ, and "Continue with Microsoft" on the login page.

What a person sees

Continue with Microsoft signs in with the account picker and asks only for name and email. A new account's onboarding then opens with an access step that offers the data connection; skipping it is fine. Existing accounts go straight where they were heading and can connect from Settings.

Connect Microsoft (Settings → Integrations, the Copilot card, or the access step) creates one microsoft connection per Microsoft account:

• Personal accounts get mail, calendar and files.
• Work or school accounts can add Teams chats, Microsoft 365 Copilot and Work IQ. Each service reports its own status: ready, needs your permission (one Allow click, or Allow everything listed), needs your admin, needs organization setup (Work IQ), or work accounts only.
• An admin can choose Approve for my whole organization, after which everyone in that tenant gets every service in one click.
• Work IQ is never asked for together with anything else, neither in "Allow everything listed" nor in the organization approval: until Microsoft has set Work IQ up for the organization, asking for it fails everything asked with it (AADSTS650052), and nothing shows that before someone asks. Its permission is admin-consent only (Microsoft marks WorkIQAgent.Ask AdminConsentRequired), so it shows "needs your admin" until an admin approves it, from its own Allow or for the whole organization. After that every existing connection gets Work IQ from its own refresh token, with no new sign-in.
• If Microsoft stops accepting a connection (an expired or revoked grant), the panel asks the person to sign in again.

Copilot chats run on a work connection that has Copilot's permissions; there is no separate Copilot sign-in. Copilot connections made before this keep working until they are disconnected.

What each permission is for

The panel, the Copilot card and the admin setup page (/microsoft-setup) say this wherever someone grants a permission.

Service	Permissions	What it lets AutoGPT do
Mail	Mail.ReadWrite, Mail.Send	Otto reads, drafts and sends the person's email.
Calendar	Calendars.ReadWrite	Otto sees, adds and changes their calendar events.
Files	Files.ReadWrite	Otto opens, creates and edits their OneDrive files.
Teams chats	Chat.ReadWrite	Otto reads and sends messages in their Teams chats.
Microsoft 365 Copilot	Copilot's read permissions (Sites.Read.All, Mail.Read, Chat.Read, …)	Microsoft 365 Copilot answers chats routed to it, from what the account can open.
Work IQ	WorkIQAgent.Ask	Otto asks Work IQ, which can read and change the person's Microsoft 365 content.

Every sign-in also asks for User.Read and openid profile email offline_access, to identify the account and keep it connected. Today the Copilot chat route is the only thing that runs on the connection; Otto's mail, calendar, files, Teams and Work IQ tools follow it.

How it works

• backend/integrations/oauth/microsoft.py: browser sign-in (authorization code with PKCE) and the sign-in-code fallback. Both produce the same credential, recording which app issued it.
• microsoft_tokens.py: token requests. Every request goes out as the app that issued the grant; only the deployment's own app sends its secret. Work IQ tokens are minted from the same refresh token: a Microsoft refresh token isn't tied to one resource, and gets tokens for any resource the app has consent for, including consent an admin gives after the sign-in.
• microsoft_services.py: services and their permissions. A sign-in may ask consent for Graph and Work IQ together; the stored token is always Graph.
• microsoft_access.py: the per-service status and the organization approval link (POST /api/integrations/microsoft/check).
• frontend/src/components/contextual/MicrosoftConnection/: the connection panel that Settings, the Microsoft 365 Copilot card and the access step share. A personal and a work account can share an address and stay separate connections.
• frontend/src/app/(no-navbar)/onboarding/steps/AccessStep/: the access step. accessProviders.tsx maps a sign-in provider to the connection it offers; Google or GitHub join by adding an entry there.
• frontend/src/lib/auth/microsoft-login.ts: the login provider. Better Auth keys accounts on Microsoft's object ID (oid), never the email address. An address only counts when Microsoft vouches for it: a personal account's own Outlook.com, Hotmail, Live or MSN address, or a work address with xms_edov. A guest's address is never trusted: a guest signs in through an organization that isn't its own, which vouches for addresses it never verified. Any other address joins no existing account (Better Auth answers account_not_linked) and creates none (microsoft-sign-up-policy.ts refuses with the same account_not_linked and no message, so the redirect is the same either way and doesn't reveal whether an account uses the address), whether or not email verification is on. "Outlook.com" here means the domains in MICROSOFT_MAIL_DOMAINS, each checked to route mail to Outlook.com's consumer servers. Sign-in reads only name and email: it asks for openid profile email and no Graph permission, and Better Auth's profile-photo fetch is switched off. Only the redirect flow signs in: Better Auth's ID-token sign-in is switched off for Microsoft. Emailing a confirmation link instead would not be safe: the mailbox's owner could confirm it, and the other person's Microsoft login would still sign in to the account. An AutoGPT team address (@agpt.co) gets an account only through Google, however Microsoft vouches for it (team_email_requires_google); a team member's existing account still signs in with Microsoft. The hook runs these Microsoft checks before the rules every provider shares, so a Microsoft sign-up gets these codes, which /login explains. Every provider's refused sign-in returns to /login with the page's next, so a deep link still opens after logging in another way. Microsoft's also carries provider=microsoft, and /login uses its Microsoft wording only then.

Moving the access step

The wizard's order is data (DEFAULT_STEP_ORDER in onboarding/store.ts), so an experiment can move a step without a code change. The onboarding-step-order flag's payload is a JSON list of step names. The steps it names lead, in its order; every other step follows in the default order, and preparing is always last. It only moves steps: which ones show still depends on the account (the access step needs a provider sign-in, the paywall needs payments on). With payments on, the access step always follows the subscription step, because connecting a service needs a plan and a new account has none until then. For example, without the paywall:

• [] (or no flag): access, team, autopilot, role, painPoints, then subscription, which shows the plan on its own, ...
• ["team", "autopilot", "role", "access"]: the access step after the role.

The order is fixed when the wizard loads, so changing the flag never reorders it under someone. Progress is saved by step name, so a later visit resumes at the right step even if the order changed in between. New steps, such as recommendations drawn from connected services where each service's terms allow it, slot into the same list.

Entra app settings (per environment)

On the environment's app (dev: autogpt-dev, prod: AutoGPT):

1. Manifest: api.requestedAccessTokenVersion = 2, then signInAudience = AzureADandPersonalMicrosoftAccount. The order matters; the audience change fails without token version 2. The Teams bot is unaffected: it authenticates against the home tenant with its own secret.
2. Web redirect URIs: {frontend}/auth/integrations/oauth_callback (data connection and organization approval) and {frontend}/api/auth/callback/microsoft (Continue with Microsoft).
3. Token configuration: add the optional ID-token claim xms_edov. Without it, work and school accounts cannot use Continue with Microsoft.
4. Certificates & secrets: the bot's existing secret also serves sign-in. Rotate by adding a new secret, deploying it, then removing the old one.
5. API permissions: add the connection's delegated Microsoft Graph permissions: User.Read, openid, profile, email, offline_access, Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, Files.ReadWrite, Chat.ReadWrite, and Copilot's Sites.Read.All, Mail.Read, People.Read.All, OnlineMeetingTranscript.Read.All, Chat.Read, ChannelMessage.Read.All and ExternalItem.Read.All. Sign-ins ask for their permissions as they go, so this changes nothing for them. It is what an admin approves when they grant consent outside AutoGPT: the Entra admin center and Microsoft's /adminconsent?client_id=… link, which /microsoft-setup points to in sign-in-code mode, approve only the permissions listed here. Leave Work IQ out: listed, it would fail that approval wherever Microsoft hasn't set Work IQ up (AADSTS650052).

Then set MICROSOFT_BROWSER_SIGN_IN=true. A secret alone doesn't turn browser sign-in on, because the bot's app has one long before it has the redirect. Until the flag is on, Microsoft connects with sign-in codes through the same app, at /common (the Copilot-only connection used /organizations). So step 1 is needed before an environment gets this release, not only before the flag: without it, personal accounts can't sign in. Continue with Microsoft has its own switch, below.

Dev's app has steps 1–4 (2026-10-26); step 5 and the flags remain. Prod needs step 1 before this release reaches it, and step 5 so an admin's approval covers every service; then steps 2 and 3 and the flags.

Environment variables

Where	Setting	Notes
backend	MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID	Shared with the Teams bot. Without a secret, connections use sign-in codes.
backend	MICROSOFT_BROWSER_SIGN_IN=true	Browser sign-in instead of sign-in codes, once the app has the redirect above.
frontend	AUTH_MICROSOFT_CLIENT_ID, AUTH_MICROSOFT_CLIENT_SECRET	Same app as the backend.
frontend	NEXT_PUBLIC_AUTH_MICROSOFT_ENABLED=true	Shows the login button.

Installs without an app secret

.env.default ships no Microsoft settings. The backend then uses AutoGPT's public client (ce01a4d6-…) with sign-in codes, so a fresh local install can still connect Microsoft and use Copilot. Browser sign-in and Continue with Microsoft need an app with a secret, the redirects above and their switches.

Testing locally

Run the normal AutoGPT stack behind one private HTTPS origin (for example a Tailscale listener), set the frontend and backend public URLs to it, and register its two callbacks on the dev app. Then:

1. Log in, open Settings → Integrations → Connect Service → Microsoft, and sign in. Check each service's status, then try Allow everything listed on a work account.
2. Open the Microsoft 365 Copilot card; a work connection with Copilot's permissions should already count as connected.
3. Log out and use Continue with Microsoft with a personal and a work account. A new account's onboarding should open on "Also connect Microsoft 365?".

Work IQ also needs Microsoft's own setup in the tenant (the fdcc1f02-… service, admin approval and Copilot Credits billing). Until then its status is "Your organization still needs to set this up".