Hard-won lessons from building a Teams-data SPA (chats, channel threads,
recordings/transcripts) against Microsoft Graph with delegated MSAL.js auth.
Real evidence throughout -- not generic API advice.
0. The one practice that pays for everything else: probe before you build
Before writing any TypeScript/app code against a new Graph capability, write a
throwaway, standalone HTML file with zero build tooling:
<script type="module">
import { PublicClientApplication } from "https://esm.sh/@azure/msal-browser";
// hardcode the real client id -- client ids are not secrets
const pca = new PublicClientApplication({ auth: { clientId: "...", authority: "..." } });
// real interactive login, then a raw fetch() to the EXACT endpoint/query
// render BOTH a summary AND the raw JSON of the first result --
// the raw JSON is "proof of shape," including undocumented-feeling fields
// like a replies[] array under $expand
</script>
This decouples two different risks: "does this scope/endpoint even return what
I expect" (cheap, interactive, real credentials, zero build step) from "is my
app's abstraction correct." A wrong assumption about Graph's actual behavior
gets caught in seconds instead of after a full feature is built on it. Delete
the probe once you have the answer -- never commit or ship it.
Treat admin-consent lead time as a hard roadmap gate: confirm consent is
available for a scope before starting the feature that needs it, not as a
mid-feature surprise. Run genuine investigation spikes (not ad hoc debugging)
for open questions, and record the negative result permanently (a commit
message, a design-doc line) so nobody re-tries a dead end later without
knowing why it failed.
1. OData / query quirks
$top can be rejected on specific sub-endpoints even when it works on
the parent -- e.g. allowed on /me/chats and /{chat}/messages, but
/me/chats/{id}/members throws Query option 'Top' is not allowed. Don't
assume a query option that works on one endpoint works on its neighbors.
$expand=replies is the only way to get thread replies inline on channel
messages: /teams/{teamId}/channels/{channelId}/messages?$top=50&$expand=replies.
There's no server-side "last activity" sort for threads -- compute
max(root.createdDateTime, all replies.createdDateTime) client-side.
No $filter on chat-message dates. Page newest-first, stop once you hit
your since boundary or run out of messages, filter client-side. This
pattern recurs everywhere Graph lacks a date filter (recordings windowing,
etc.) -- assume no server-side date filter until proven otherwise.
@odata.nextLink is an absolute URL -- pass it straight to fetch(),
don't re-prefix it with your base URL.
$count support is not universal across endpoints (e.g. transcript
endpoints don't support it) -- declare per-source capabilities and adapt
UI/warnings rather than assuming uniform support.
Resource IDs aren't always interchangeable even when they look similar --
e.g. Teams chat IDs are MRIs starting with 19:; passing an Exchange/Outlook
item ID (AAMk...) to a chat endpoint returns 400 "Invalid MRI, should start with digits and colon". Validate ID shape client-side before firing
the request.
2. Permissions & consent
Split app registrations by trust boundary. One app for auth-gate/login
scopes only (openid, profile, email); a separate app for the actual
Graph content scopes. A leaked login credential then can't pivot to content
access.
Grow scopes incrementally, tied to feature order, and be willing to
drop scopes a prior approach needed once you replace that approach (e.g.
dropping calendar/online-meetings scopes entirely once a chat-based
discovery method replaced the calendar-based one -- see §3).
Transcript access needs a different API resource's permission --
Sites.Read.All under "Office 365 SharePoint Online" is not the same grant
as Microsoft Graph's own Sites.Read.All, and backs a different bearer
token (https://{spHost}/.default).
Fingerprint consent errors and degrade gracefully, don't retry-loop.
Match /AADSTS65001|invalid_grant|InteractionRequiredAuthError/i against the
error; on match for an optional feature, set a session-scoped flag that
suppresses further attempts for the rest of the page session (self-heals on
reload once the scope is granted) instead of spamming retries or the
console.
Nested-group and mail-enabled-group gotchas (general Entra knowledge):
AADSTS50105 fires when a role assignment flows through a nested
subgroup (must be a direct member for app-role assignment); a
mail-enabled security group silently fails to emit the roles claim even
though the portal shows the assignment as successful (recreate as a pure
security group); the groups claim is replaced by
_claim_names/_claim_sources once a user is in 200+ groups (resolving
needs an OBO call with a client secret -- generally blocked for pure SPAs,
so prefer app roles over group claims when overage is possible).
3. Recordings / transcripts -- the hardest-won findings
/me/onlineMeetings transcript/recording endpoints are a confirmed dead
end for "recordings I can access" -- they only work for meetings the
signed-in user organized.getAllTranscripts()/getAllRecordings()
enforce userId == organizerId; the meetingOrganizerUserId=null "get all"
syntax doesn't work at v1.0 or beta (both 400); passing your own oid returns
412 "not supported in delegated context." /search/query for
filetype:mp4 returns 0 results under delegated auth.
The working alternative: walk /me/chats messages and read
eventDetail[\"@odata.type\"] === \"#microsoft.graph.callRecordingEventMessageDetail\"
directly out of the message payload. This surfaces recordings regardless
of who organized the meeting, including recordings in another user's
OneDrive. Cross-join participants from sibling callEndedEventMessageDetail
events by shared callId, falling back to plain chat membership when no
callEnded event exists (ad-hoc 1:1 calls never emit one).
The real access boundary is SharePoint ACL on the recording file, not
meeting organizer. The "organizer-only" gate is an artifact of the
/me/onlineMeetings API specifically -- not a real data limit. This
reframing is the core insight: chat-membership access ≠ organizer access,
and Graph's official transcript API enforces the wrong boundary.
Transcript retrieval is SharePoint REST v2.1, not Graph:
GET /shares/{shareId}/driveItem (Graph, Files.Read.All) to resolve
driveId/itemId from a sharing URL. shareId = "u!" + base64url(url),
strip = padding.
GET https://{spHost}/_api/v2.1/drives/{driveId}/items/{itemId}?select=name,media/transcripts&$expand=media/transcripts
-- Graph does not expose media/transcripts; this is a separate
SharePoint-resource bearer token (https://{spHost}/.default), not the
Graph token.
Rewrite temporaryDownloadUrl to /streamContent?is=1&applymediaedits=false
to get raw VTT.
Try with the bearer token first, fall back to unauthenticated fetch on
401 (a hosted SPA needs the SP token; a browser extension could ride
cookies but a hosted app can't).
Cross-tenant recordings are a typed non-error./shares/{id}/driveItem
returns 400 "Invalid hostname for this tenancy" when the file lives in
another org's SharePoint -- give this its own error type so callers can
count/label it, not treat it as a bug.
Shallow pagination silently drops data. A naive top-50 scan dropped 11
of 38 recordings in a 30-day window. Deep-scan each in-window container
until you pass the window edge or hit a page cap; if the cap fires first,
flag the result truncated: true and say so loudly in the UI -- never
silently incomplete.
Validate defensive assumptions empirically before keeping them. A
padded date-window buffer (in case a container's "last updated" timestamp
was stale) was later disproven with a full-scan oracle across hundreds of
containers -- the timestamp was always current, the buffer was pure
overhead. Removing it cut the scan size substantially.
Different environments/tenant rings can use different SharePoint
hostname patterns. If your app runs across multiple tenants or
environments (production, staging, internal test rings), verify the
actual SharePoint hostname per environment rather than assuming one
wildcard covers all -- each distinct host pattern needs its own
CSP/allowlist entry.
4. CSP for a pure-browser SPA calling Graph directly
Built up incrementally -- every addition was driven by a production-only
failure the local dev server never surfaced, since CSP is browser-enforced,
not dev-server-enforced:
style-src 'unsafe-inline' -- dynamic inline styles, invisible until prod.
connect-src *.sharepoint.com -- OneDrive AppFolder sync + transcript
downloads share one wildcard (add further host patterns per environment,
see §3's last point).
frame-src entries were added to support an ssoSilent hidden-iframe
approach that was later ripped out entirely (§6) -- left in place as
harmless once no longer load-bearing. Lesson: a CSP entry added for one
strategy can outlive that strategy -- don't assume every entry still has
a live purpose; don't be surprised when removing a CSP entry breaks nothing.
5. Rate limiting / retry / pagination
Retry only 429, 502, 503, 504. Everything else (400/401/403/404…)
throws immediately with the (truncated) response body in the error -- never
blind-retry a client error.
429: honor Retry-After (seconds), clamp to a sane max (~60s) against a
misbehaving value.
502/503/504: exponential backoff + jitter when no Retry-After (e.g.
~1s doubling, capped ~30s, random jitter to avoid thundering-herd retries).
Cap at ~5 attempts, then throw loud with status + attempt count +
truncated body.
Refresh the token on every retry, not just once -- a long paginated
scan across hundreds of items shouldn't die to a token that expired
mid-scan.
Bounded concurrency pool (e.g. 4 workers) for bulk enumeration, not
unbounded Promise.all over hundreds of items -- bounds throttling risk.
Start with observability-only for rate limiting (log/capture 429s and
scope failures as a signal) rather than building custom retry dashboards
before you know if you even need them.
6. MSAL.js / EasyAuth -- the auth-loop debugging saga
This was the single most-iterated area. Presented as a sequence because the
sequence is the lesson: four plausible-looking root causes in a row were
wrong, and each "fix" that didn't work still taught something.
Wrong-ish: assumed CSP frame-src was too strict for MSAL's hidden
ssoSilent iframe returning to the app's own origin. Added 'self' to
frame-src. Loop persisted.
Still incomplete: the iframe also needed the platform's own identity
host in frame-src to ride an existing session cookie. Added it. Loop
persisted.
The CSP fixes were a red herring. Real cause: modern browsers block
third-party session cookies in same-frame contexts, and the identity
provider refuses to render its login page in an iframe at all
(X-Frame-Options: deny) -- unfixable from the app side. Fix: remove
the iframe-based silent-SSO bridge entirely, fall through to a full
top-level redirect login (no iframe, so X-Frame-Options doesn't apply).
Accepted UX cost: one click instead of a broken zero-click bridge.
Loop persisted even without the iframe. Actual root cause: the
platform's own catch-all "require auth on every route" rule intercepted
MSAL's own redirect-return navigation (which carries the auth code in a
URL fragment) and stripped the fragment before MSAL could read it -- so
MSAL never established a session. Fix: add an anonymous callback route
(e.g. /auth-callback) above the catch-all auth rule; point
redirectUri at it; only navigate into the app after
handleRedirectPromise() resolves an account. Confirmed by checking the
console showed zero CSP violations during the failure -- proof it was
never a CSP problem, which is what fixes 1-2 had assumed.
Write the decision + dead-ends down permanently once solved, so a
future session with a similar symptom doesn't re-litigate the same wrong
hypothesis (CSP) again.
A related but distinct bug: an un-awaited "try silent login" call at
module top-level blocked first paint for the iframe's multi-second
timeout -- a white-screen bug, not a loop. Fix: make it non-blocking with
a visible "Signing in..." placeholder.
Net architecture: no iframe-based silent SSO. On load: init →
handleRedirectPromise() → if on the callback route with an account now
set, client-side redirect to / → else reuse a cached account if present
→ else show a sign-in button that does a full top-level redirect login.
Per-Graph-call fallback is separate: try silent token acquisition first;
on failure, redirect interactively for that scope set and let the navigation
handle it -- don't try to recover in place.
Deployed-vs-local config drift is its own bug class: when two different
env vars can each answer "which app is this" (e.g. one injected by your
deploy platform, one injected by your build tool), get the precedence
order right and know which one actually carries your full scope set --
getting it backwards silently breaks a specific feature only in the
deployed build, invisible in local dev where only one var is set. Test the
newest feature specifically against the deployed build, not just locally.
7. Other gotchas
Sibling resource types (chats vs. channels) can have materially
different Graph surfaces and scope requirements even though they feel
like the same product area to a user -- investigate each independently,
don't assume parity.
Client-side date-range windowing is the default assumption, not the
exception -- "page newest-first, stop once a whole page is provably older
than your window" beats hoping for a $filter that doesn't exist.
A 403 on one item in a bulk enumeration should be a typed, silent
"no access" for that item -- pattern-match 403/forbidden/access-denied
and convert to a skip or a labeled UI state, so one inaccessible item
doesn't abort enumeration of everything else.
Synthesize your own composite/stable ID when Graph doesn't provide one
spanning a hierarchy (e.g. teamId::channelId, or callId::filename when
one call can produce multiple recording files).
Re-evaluate narrow "selected files" scopes against broad ones once admin
consent removes the security argument for going narrow -- the narrower
scope's interactive picker can add UX friction with no remaining benefit.
Graph itself won't merge concurrent writes to shared state. Use
conditional writes (ETags/If-Match) on any shared blob you sync through
Graph-backed storage, and handle 412 Precondition Failed with a
re-read-and-merge (set-union for additive fields, last-write-wins per key
for scalars).
