Migrating from a Custom WOPI Host to SharePoint Embedded: A Practical Playbook

Migrating from a Custom WOPI Host to SharePoint Embedded: A Practical Playbook

This is the article that two earlier pieces in our Q2 2026 series have been pointing toward. We have explained what SharePoint Embedded is. We have walked through the decision framework for SharePoint Embedded vs WOPI. We have built a SharePoint Embedded application end-to-end. The remaining question for many existing WOPI hosts is the migration question: should we move from our custom WOPI host to SharePoint Embedded, and if so, how?

This article is the playbook. It is structured as four parts: the strategic decision (when migration genuinely makes sense), the architectural mapping (how WOPI concepts translate to SharePoint Embedded equivalents), the migration mechanics (data, identity, URLs, deployment), and the phased rollout (pilot, controlled, full, decommissioning). It is written for ISVs and enterprise architects who are evaluating or planning a migration.

Before reading further: this is not a small project. A realistic migration of a non-trivial WOPI host is a multi-month engagement, often longer. The article is honest about that. McKenna Consultants delivers these migrations as packaged engagements, and the patterns described here reflect what we have learned in production migration work.

Part One: When Migration Genuinely Makes Sense

Not every WOPI host should migrate. The strategic question is whether SharePoint Embedded offers enough advantage, in your specific situation, to justify the migration cost.

The cases where migration is the right call:

Operational burden reduction. Your WOPI host requires standing operational investment — discovery uptime, certificate management, proof key rotation, Office release tracking — and that investment is not a strategic differentiator for your business. SharePoint Embedded eliminates this entire surface area. For organisations whose engineering capacity is the binding constraint, the operational simplification is genuinely transformative.

Native coauthoring without further investment. Your product roadmap includes coauthoring, sensitivity labels, retention policies, or Microsoft Purview integration. Building these on top of a custom WOPI host is a substantial engineering project. SharePoint Embedded gives them to you for free.

Microsoft 365 Copilot integration. Your product strategy includes Copilot capabilities or custom Copilot agents. SharePoint Embedded is the most direct path to making your product’s documents Copilot-grounded; the WOPI path is more involved and produces a less complete integration.

Customer demand for SharePoint Embedded. Increasingly, enterprise buyers ask “is this SharePoint Embedded?” rather than “is this WOPI?”. For ISVs whose go-to-market depends on Microsoft alignment, the platform position itself has commercial value.

Reduction in compliance complexity. Your customers’ compliance teams are increasingly interrogating the storage layer of your application. A SharePoint Embedded-backed application can answer these questions by reference to Microsoft’s certifications and information protection model, rather than by re-establishing your own. For some customer segments — regulated industries, public sector — this materially shortens the procurement cycle.

The cases where migration is the wrong call:

Established CSPP Plus features in production. If your application uses backstage integration, CSPP Plus geo-fencing, or chunked file transfer, those capabilities do not have direct SharePoint Embedded equivalents. Migration would be a feature regression unless the product strategy can absorb the loss.

Storage as the product. If your application’s commercial proposition is “we are your storage” — document management, enterprise content management, cloud storage — migration to SharePoint Embedded gives the storage to Microsoft. This is rarely strategically acceptable for storage-centric businesses.

Hard data residency requirements outside Microsoft’s footprint. SharePoint Embedded operates within Microsoft’s regional infrastructure. If your customers require storage in jurisdictions Microsoft does not serve, or in customer-controlled data centres, SharePoint Embedded cannot meet the requirement.

Existing CSPP partner relationship with strategic value. Your Cloud Storage Partner Program membership has commercial value beyond the technical integration — Microsoft account team relationships, joint go-to-market motion, product co-marketing. Walking away from CSPP for the migration eliminates that value.

The cost of migration outweighs the benefit. A minimum-viable WOPI host that already serves a small customer base with low operational burden may not be worth migrating. The benefit must justify the migration cost.

McKenna’s strong recommendation is to make this decision deliberately, with a documented rationale, before any code is written. The migration is too significant to enter on an unexamined assumption.

Part Two: Architectural Mapping

For organisations that have decided to migrate, the second question is how WOPI concepts map onto SharePoint Embedded equivalents. The mapping is mostly clean, with a few specific points of friction.

WOPI Concept	SharePoint Embedded Equivalent	Notes
WOPI host	Your application registration in Microsoft Entra ID	The “host” is no longer a distinct technical role; your application talks to Graph
Discovery document	Microsoft Graph endpoints (no separate discovery)	Microsoft handles discovery internally
WOPI access tokens	Microsoft Graph delegated and application tokens	Standard OAuth 2.0 via MSAL
Proof keys	Not applicable	No host-side token validation; Microsoft validates Graph tokens
File store	SharePoint Embedded containers	Microsoft hosts the storage
File metadata (CheckFileInfo)	Container and drive item properties via Graph	Standard Graph drive item model
File operations (GetFile, PutFile)	Graph drive item content endpoints	Standard Graph file APIs
Lock management (Lock, Unlock, RefreshLock)	Handled by Microsoft inside the platform	No host-side lock state to manage
Coauthoring	First-class capability	No additional implementation
User identity (HostAuthenticationId)	Entra ID user identity, available via Graph	Standard Entra ID user objects
Permissions and authorisation	Container permissions API, with role-based grants	Reader, writer, manager, owner roles
Sensitivity labels and retention	Inherited from consuming tenant configuration	Automatic
Audit logs	Consuming tenant unified audit log	Standard Microsoft 365 audit surface
File URLs	Drive item webUrl and constructed editing URLs	Different URL scheme from your existing WOPI URLs
Office for the web rendering	First-class	Same Office for the web infrastructure
Mobile editing	Office mobile apps, opening container files via Graph	Different app integration than mobile WOPI

The points of friction worth highlighting:

Lock management disappears entirely. WOPI hosts spend a non-trivial amount of effort implementing the lock state machine correctly. In SharePoint Embedded, locking is handled inside the platform. The code your team has been carefully maintaining for years simply does not exist on the SharePoint Embedded side. This is a genuine simplification.

File URLs change. Every URL pointing at a file in your old WOPI host is invalidated by migration. URLs in emails, in CRM records, in SharePoint sites that link to your storage, in customer-side bookmarks — all of them need addressing. A redirect layer at your old domain, mapping old WOPI URLs to new SharePoint Embedded equivalents for as long as references remain in flight, is a non-negotiable component of the migration plan.

The user identity model changes shape. WOPI integrations frequently use the host’s own identity model and translate to WOPI user identifiers via HostAuthenticationId. SharePoint Embedded uses Entra ID user identity directly. For applications whose user identity is not currently Entra ID-based, this is a significant transition — the application’s identity layer must federate with Entra ID, or users must have Entra ID identities provisioned, before SharePoint Embedded can authenticate them. This is often the single largest migration sub-project.

CSPP-specific features may have no equivalent. If your application uses CSPP backstage integration, the product manager’s first question on the migration plan should be “what replaces backstage?” There is no like-for-like answer. Migration involves a product decision about the future of the backstage user journey.

Part Three: Migration Mechanics

Once the decision is made and the mapping is understood, the migration itself has six workstreams.

Workstream 1: Identity and Authentication

The first migration step in nearly every plan is the identity workstream. Your application must:

• Register in Microsoft Entra ID as outlined in the SharePoint Embedded implementation guide.
• Establish federation between your existing user identity model and Entra ID, or migrate users to Entra ID-native identities.
• Update authentication flows to acquire Microsoft Graph tokens rather than (or alongside) WOPI access tokens.
• Update token storage and refresh logic for the OAuth 2.0 flow.

For applications that already use Entra ID for primary user authentication, this workstream is straightforward. For applications with their own identity models (custom OIDC providers, legacy authentication systems, or hybrid setups), it is substantial.

The authentication workstream often runs in parallel with the rest of the migration, because the rest of the work depends on having Graph tokens to call.

Workstream 2: Container Type Registration and Customer Onboarding

The container type registration workstream:

• Design the container type model (one type? Multiple? What permissions structure?).
• Register the container type in your application tenant.
• Build the consuming-tenant authorisation flow into your application onboarding.
• Communicate the new authorisation requirement to existing customers — every existing customer must complete the consuming-tenant authorisation as part of migration.

The customer-side communication piece is often underestimated. A customer who must perform a one-time admin consent flow to enable migration is a customer who must be contacted, prepared, and supported through the consent. For customers with hundreds of seats, this is a project management exercise in itself.

Workstream 3: Data Migration

The data workstream moves files from your existing storage into SharePoint Embedded containers. The pattern that works best:

• Build a migration tool that reads from your current storage, creates the corresponding container (if not already present), and uploads the file content via Graph. The tool should be idempotent — running it twice on the same source should produce a single result.
• Map source identities to target containers. Most existing WOPI hosts have their own concept of “tenant” or “workspace” that maps onto SharePoint Embedded’s container concept. The mapping is often non-trivial and requires application-domain expertise.
• Preserve metadata where it is preserved-able. SharePoint Embedded supports drive item metadata, but your existing WOPI metadata may have shapes that do not map cleanly. Decide what metadata is preserved, what is dropped, and what is reconstructed from application context.
• Handle versioning. If your existing storage has version history, decide whether to migrate the history into SharePoint Embedded version history or to flatten to current state. Both are valid choices; the implications differ for compliance and support.
• Run the migration in batches. A full migration of a large estate cannot be a single operation — it must be batched, observable, and resumable.

The migration tool should be production-grade code, not a one-shot script. It will run multiple times during the migration — a pilot run, several rehearsals, the actual cutover — and its correctness is critical.

Workstream 4: URL Redirect and Reference Mapping

Every URL pointing at your old WOPI host must be addressable after migration. The pattern:

• Stand up a redirect service at your old WOPI host’s domain that maps old URLs to new SharePoint Embedded equivalents.
• Maintain the mapping for the duration of the migration and beyond — typically twelve to twenty-four months — to handle URLs that linger in emails, CRM records, customer bookmarks, and external systems.
• Instrument redirect traffic so you can see when old URLs are still being hit and from where. This visibility informs the decision about when to retire the redirect service.
• Communicate with external systems that hold long-lived references to your URLs (CRM integrations, partner systems, regulatory recordkeeping). Some references must be updated proactively.

The redirect surface is operationally less work than a full WOPI host but cannot be neglected. A migration that breaks customer-facing URLs erodes trust in ways that are hard to recover.

Workstream 5: Application Layer Changes

Your application code must change in several places:

• Replace WOPI client interactions with Graph drive operations. File listing, content access, upload, download — all of these move from your WOPI host endpoints to Graph endpoints.
• Update embedded editor invocation. Replace the WOPI launch URL construction with the SharePoint Embedded URL construction.
• Move permissions management into the SharePoint Embedded API. Stop maintaining your own permission state for migrated containers; let SharePoint Embedded permissions be the source of truth.
• Update telemetry and monitoring. Graph operations have their own observability surface (request IDs, throttling responses); your monitoring needs to cover this.
• Update support tooling. Customer support representatives have tools that reference your WOPI infrastructure; these tools need updating to look at SharePoint Embedded equivalents.

This workstream is the bulk of the engineering effort and is best run as a sequence of feature-flagged changes that allow per-customer or per-environment toggling between the old WOPI path and the new SharePoint Embedded path during transition.

Workstream 6: Decommissioning

The final workstream retires the WOPI infrastructure once all customers are migrated. This includes:

• Decommissioning the WOPI host endpoints. After confirming no traffic, the discovery document, the file information endpoints, the content endpoints, and the proof key infrastructure are all retired.
• Retiring CSPP partner status, if migration takes you out of the partner programme.
• Archiving the source storage layer. The data is no longer authoritative — but for compliance and dispute resolution purposes, the original storage may need to be retained in cold storage for a defined period.
• Updating documentation, contracts, and product collateral. The new platform position must be reflected in the customer-facing materials.

Part Four: Phased Rollout

A controlled migration uses four phases, with explicit decision gates at the boundary of each.

Phase 1: Internal Pilot. Migrate one internal use case — a McKenna engagement might use a small internal application or a synthetic test customer. Validate the end-to-end flow, refine the migration tool, and surface the operational issues that only appear under realistic load.

Phase 2: Friendly Customer Pilot. Identify two or three customers who are candid about issues, willing to go first, and operationally tolerant of the transition. Migrate them, shadow them through the change, and document the issues that emerge. The output of this phase is a proven migration runbook.

Phase 3: Controlled Rollout. Migrate cohorts of customers in defined batches — perhaps 5%, 15%, 35%, 70% over a series of waves. Each wave should have a defined go / no-go gate with success criteria. The criteria are usually a combination of technical (no significant Graph errors, no data loss) and customer (no spike in support volume, no customer-reported regressions).

Phase 4: Full Cutover and Decommissioning. Migrate the long tail and retire the WOPI infrastructure. The long tail includes the inevitable hold-out customers — the ones with custom integrations, the ones whose authorising administrators are hard to schedule, the ones who simply prefer the old way. A defined cutover date with appropriate notice is the typical mechanism, with bespoke handling for the very largest accounts.

A realistic timeline for a non-trivial migration:

• Decision and architecture: four to six weeks
• Identity workstream and container type registration: four to eight weeks
• Migration tool development and rehearsal: six to ten weeks
• Internal and friendly pilot: four to eight weeks
• Controlled rollout: eight to sixteen weeks (depending on customer count and cohort size)
• Full cutover and decommissioning: four to eight weeks

End-to-end, this is six months minimum for a small estate, twelve months realistic for a substantial estate, longer for very large or complex estates.

What McKenna Delivers

McKenna Consultants delivers WOPI-to-SharePoint-Embedded migration as a structured engagement with the four phases above. Our typical engagement model:

Strategy and architecture. Decision framework analysis, architectural mapping, migration plan development, customer communication strategy. Output: a documented migration plan with the workstreams, dependencies, and timeline.

Implementation. The six workstreams above, run in parallel where feasible. Output: working SharePoint Embedded application alongside the existing WOPI infrastructure, ready for pilot migration.

Pilot and rollout. Migration tool refinement, pilot customer migration, controlled rollout of the broader estate. Output: customers migrated to SharePoint Embedded, with the WOPI infrastructure scoped for retirement.

Decommissioning. Final retirement of WOPI endpoints, CSPP exit (if applicable), source storage archive. Output: clean SharePoint Embedded operational state.

We are equally fluent in WOPI and in SharePoint Embedded — we built our practice on WOPI and are now extending it to SharePoint Embedded — which means we approach the migration as an architectural transition rather than as advocacy for either platform. If your organisation is evaluating or planning a migration, contact us to discuss the engagement.