What SSO With Microsoft Means in Practice
Single sign-on (SSO) with Microsoft lets users access your Office add-in, Teams app, or web app using the Microsoft 365 account they are already signed into — no second username and password. Under the hood it relies on Microsoft Entra ID (formerly Azure AD) and standard OAuth2 and OpenID Connect. For an Office add-in, Office.js exposes getAccessToken(), which hands your add-in a token representing the current user; your server then exchanges it, using the on-behalf-of flow, for a token that can call Microsoft Graph. The result feels seamless to the user and keeps you out of the business of storing passwords — but it has a few sharp edges that every production add-in has to handle.
Key Takeaways
Entra ID identity
SSO is built on Microsoft Entra ID (Azure AD) with OAuth2 and OpenID Connect.
getAccessToken() in add-ins
Office.js returns a bootstrap token identifying the signed-in Microsoft 365 user.
On-behalf-of flow
Your server swaps the bootstrap token for a Graph token to act for that user.
App registration + scopes
Register the app in Entra ID, expose an API, and declare the Graph scopes you need.
Admin consent
Some scopes require a tenant admin to consent once for the whole organization.
Always build a fallback
SSO can silently fail; an interactive MSAL dialog must be ready to take over.
The SSO Token Flow — and the Fallback People Forget
Here is the flow for an Office add-in: the add-in calls Office.js getAccessToken() to get a bootstrap token for the signed-in user; it sends that token to your back-end; your back-end uses the on-behalf-of flow against Entra ID to obtain an access token for Microsoft Graph; and then it calls Graph and returns the results. Teams apps follow an equivalent pattern with Teams SSO. The setup work lives in the Entra ID app registration — exposing your API, defining scopes, and configuring which Graph permissions are needed, some of which require one-time admin consent.
The part teams underestimate is failure handling. SSO does not always succeed: guest accounts, certain conditional-access policies, unsupported Office builds, or missing consent can all cause getAccessToken() to fail. Without a fallback, the user just sees a broken add-in. The fix is to detect those failures and fall back to an interactive sign-in using MSAL in a dialog, so the user can authenticate manually and continue.
Ship the interactive MSAL fallback from day one
Treat SSO as the happy path, not the only path. Detect getAccessToken() failures and open an interactive MSAL login dialog as a fallback. Teams that skip this ship add-ins that work on the developer's machine and mysteriously fail for guests, locked-down tenants, and older Office builds.
Done right, Microsoft SSO removes a login screen and a password store while keeping access secure. Wire up getAccessToken(), the on-behalf-of flow, and proper scopes — and always include an interactive fallback for the cases SSO cannot cover.
Orfys implements Microsoft SSO and Graph access for Office add-ins and Teams apps — including the interactive fallback that production apps require. See our page.Office Add-in development services
SSO happy path vs interactive fallback
| Scenario | SSO (getAccessToken) | Interactive MSAL fallback |
|---|---|---|
| Normal tenant user | Works silently | Not needed |
| Guest accounts | May fail | Required |
| Conditional access policies | May fail | Required |
| Older Office builds | May fail | Required |
| Missing admin consent | Fails | Required + admin must consent |
| AppSource submission requirement | Required | Required — must include both |
Frequently asked questions
What is Microsoft SSO in the context of an Office add-in?
It lets users access your add-in automatically using the Microsoft 365 account they are already signed into, via Office.js's getAccessToken() method. Your back-end exchanges that token for a Microsoft Graph token using the on-behalf-of flow.
What is the on-behalf-of flow?
It is an OAuth2 token exchange where your back-end server receives the bootstrap token from getAccessToken(), sends it to Microsoft Entra ID, and gets back an access token that can call Microsoft Graph on behalf of the user — without requiring a second login.
What happens when getAccessToken() fails?
Guest accounts, conditional-access policies, missing consent, and older Office builds can all cause it to fail. Your add-in must detect these failures and open an interactive MSAL sign-in dialog as a fallback. Without it, the add-in is broken for a meaningful share of users.
Is the interactive fallback required for AppSource?
Yes. AppSource requires that add-ins with SSO include a working interactive fallback flow. Reviewers test both paths, and a missing fallback is one of the most common reasons an add-in submission is rejected.
Seamless sign-in, with a reliable fallback
SSO with Microsoft makes add-ins and Teams apps feel effortless and keeps authentication secure on Entra ID. The flow is well-defined, but the interactive fallback is non-negotiable in production. Orfys implements Microsoft SSO and Graph access for add-ins and Teams apps.