Migrating from Legacy Document Management to CSPP Plus

Organisations across the UK are still running legacy on-premises document management systems — platforms that were deployed a decade or more ago and have served the business reliably but are now showing their age. The documents are accessible internally, but enabling modern collaborative editing, mobile access, and browser-based document viewing requires users to download files, edit them locally, and re-upload. It is a workflow that belongs to 2010, not 2025.

The path forward is the Cloud Storage Partner Program Plus (CSPP Plus), Microsoft’s programme that allows third-party applications to embed Microsoft 365 document editing — Word, Excel, PowerPoint, and Visio — directly in the browser. The underlying technology is WOPI, the Web Application Open Platform Interface protocol, which governs how a host application (your document management system) communicates with Microsoft’s Office Online servers.

At McKenna Consultants, we are one of the UK’s leading WOPI integration consultancies. We have helped SaaS companies and enterprise organisations integrate WOPI into their platforms, navigate the CSPP Plus onboarding process, and go live with Microsoft 365 document editing. This article is a practical guide for organisations considering the migration from legacy document management to a CSPP Plus-enabled architecture.

Why Legacy DMS Platforms Are Becoming a Liability

Legacy document management systems — whether built on SharePoint on-premises, OpenText, Documentum, Alfresco, or a bespoke internal solution — typically share several characteristics that are increasingly problematic.

No Browser-Based Editing

Users must download a document, edit it in a locally installed copy of Microsoft Office, and upload the changed file. This creates version control problems, prevents real-time collaboration, and excludes users on devices where Office is not installed.

No Real-Time Co-Authoring

When two people need to work on the same document simultaneously, legacy systems offer no solution beyond “wait until the other person is finished.” File locking prevents data loss but kills productivity. The modern expectation — multiple cursors in the same document, changes merging in real time — is simply not available.

Limited Mobile Access

On-premises DMS platforms are typically accessible only from the corporate network or through a VPN. Mobile access is either unavailable or limited to read-only viewing through a clunky web interface. Remote and hybrid workers are underserved.

Mounting Maintenance Costs

The servers, storage arrays, backup infrastructure, and networking equipment that support on-premises document management require ongoing maintenance, patching, and eventual replacement. The operational cost is substantial and rising, particularly as hardware reaches end-of-life.

Integration Constraints

Modern business applications — CRM, ERP, project management, HR systems — expect to integrate with document storage through APIs. Legacy DMS platforms often lack modern API surfaces, forcing integrations through file system access, database queries, or vendor-specific protocols that are expensive to maintain and fragile to extend.

What CSPP Plus Enables

CSPP Plus, through WOPI, enables your document management system to offer the same editing experience that users get in SharePoint Online and OneDrive. When a user clicks on a Word document in your application, it opens in the browser for full-featured editing — formatting, track changes, comments, real-time co-authoring — without leaving your application’s interface.

The key capabilities include:

Full-fidelity editing. Word, Excel, PowerPoint, and Visio documents render and edit with the same fidelity as the desktop Office applications.
Real-time co-authoring. Multiple users can edit the same document simultaneously, with changes merging in real time and each user’s cursor visible to others.
View-only rendering. Documents can be displayed in read-only mode for users who should not have edit access, eliminating the need for PDF conversion for viewing purposes.
Cross-platform access. Browser-based editing works on any device with a modern browser — Windows, Mac, Linux, iOS, Android, Chromebooks.
Embedded experience. The Office editor loads within your application’s interface (typically in an iframe), preserving your application’s navigation, branding, and user context.

Architecture Patterns for Migration

Migrating a legacy DMS to CSPP Plus does not necessarily mean replacing the entire system. Several architecture patterns allow you to introduce WOPI-based editing alongside your existing document storage.

Pattern 1: WOPI Layer on Existing Storage

The most conservative approach adds a WOPI host layer on top of your existing document storage infrastructure. Your legacy DMS continues to manage the file system, metadata, permissions, and search. A new WOPI host service sits alongside it, implementing the WOPI protocol endpoints that Microsoft’s Office Online servers call when a user opens or saves a document.

This pattern preserves your existing investment in document management infrastructure while enabling modern editing capabilities. It is particularly suitable when:

The legacy DMS has a stable API or file system interface that the WOPI host can consume
Document metadata, permissions, and workflows are heavily customised and would be expensive to migrate
The organisation wants to pilot WOPI-based editing with minimal disruption before committing to a larger migration

The WOPI host service needs to implement several core endpoints. CheckFileInfo returns metadata about a file — its name, size, owner, permissions, and various capability flags. GetFile returns the file contents as a binary stream. PutFile accepts updated file contents after editing. Lock and Unlock manage file locking to prevent conflicting edits.

Pattern 2: Hybrid Cloud-and-On-Premises

For organisations that are not ready to move all document storage to the cloud but want to start the transition, a hybrid architecture allows new documents to be created in cloud storage while legacy documents remain on-premises. Both storage backends are fronted by a unified WOPI host that routes requests to the appropriate storage layer based on document location.

This pattern works well when:

The organisation has a long-term cloud migration strategy but cannot move everything at once
Regulatory or compliance requirements mandate that certain document categories remain on-premises
The volume of legacy documents is too large for a practical bulk migration

Pattern 3: Full Cloud Migration

The most transformative approach migrates all document storage to a cloud-native backend — Azure Blob Storage, AWS S3, or a cloud-native DMS — with a WOPI host built on top. This eliminates the on-premises infrastructure entirely and provides the cleanest architecture for long-term maintenance.

This pattern is appropriate when:

The organisation is committed to a cloud-first strategy
On-premises infrastructure is approaching end-of-life
The legacy DMS has limited customisation that can be replicated in the new platform
Data residency requirements can be met by the chosen cloud provider’s regional deployments

WOPI Discovery and Domain Allow-Listing

Before your WOPI host can connect to Microsoft’s Office Online servers, you must complete the CSPP Plus onboarding process. A critical component of this process is domain allow-listing, and understanding the timeline is essential for project planning.

The WOPI Discovery Process

WOPI discovery is the mechanism by which your host application learns which Office Online actions are available and how to invoke them. Your application fetches a discovery XML document from Microsoft that lists the supported file types, the available actions (view, edit, editnew), and the URLs for each action.

In production, the discovery endpoint is specific to your CSPP Plus agreement. During development and testing, Microsoft provides a test environment (the “dogfood” environment) that allows you to develop and validate your WOPI implementation before going live.

Domain Allow-Listing Timeline

Microsoft must allow-list the domains from which your WOPI host will serve documents. This is a security requirement — it ensures that only approved applications can invoke Office Online editing.

The allow-listing process typically takes 4-5 weeks from submission to activation. This timeline is controlled by Microsoft and cannot be significantly accelerated. It is one of the most common sources of project delay because teams do not account for it in their planning.

Plan for this timeline from the start. Submit your domain allow-listing request as early as possible in the project — ideally as soon as you have confirmed the production domain names. You can develop and test against the dogfood environment while waiting for production allow-listing.

If your application serves documents from multiple domains (for example, if you white-label the platform for different clients), each domain must be individually allow-listed. For SaaS platforms with many customer subdomains, discuss the domain pattern with Microsoft during the onboarding process to agree an appropriate allow-listing approach.

Proof Key Validation

WOPI proof key validation is a security mechanism that ensures the WOPI requests your host receives genuinely originate from Microsoft’s Office Online servers and have not been tampered with in transit. Implementing proof key validation correctly is mandatory for CSPP Plus compliance.

How Proof Keys Work

When Microsoft’s Office Online servers send a request to your WOPI host (for example, a CheckFileInfo or GetFile request), they include two HTTP headers: X-WOPI-Proof and X-WOPI-ProofOld. These headers contain cryptographically signed data that your host can verify using the public keys published in the WOPI discovery XML.

The signed data includes the access token, the request URL, and a timestamp. Your host reconstructs the expected signed data from the incoming request, then verifies the signature using Microsoft’s public key. If the verification fails, the request should be rejected.

Common Implementation Pitfalls

Proof key validation is conceptually straightforward but has several implementation details that commonly cause failures.

URL encoding mismatches. The URL used in signature verification must exactly match the URL as constructed by Microsoft, including query string parameter ordering and encoding. A common error is to normalise or re-encode the URL before verification, which changes the bytes that were signed and causes verification to fail.

Key rotation handling. Microsoft periodically rotates the proof keys published in the discovery XML. The X-WOPI-ProofOld header exists to handle the transition period — it contains the signature made with the previous key. Your implementation must check both the current and old proof keys to avoid rejecting legitimate requests during key rotation.

Timestamp validation. The timestamp in the proof data should be checked to prevent replay attacks. Requests with timestamps more than 20 minutes old should be rejected, with appropriate allowance for clock skew.

Byte order. The proof signature is constructed from byte arrays in a specific order (access token bytes, URL bytes, timestamp bytes), each prefixed with a 4-byte big-endian length. Getting the byte order or length encoding wrong is a frequent source of validation failures.

McKenna Consultants has extensive experience with WOPI proof key validation across multiple technology stacks. If your team is encountering validation failures during development, our WOPI integration consultancy service can help diagnose and resolve the issues efficiently.

Data Residency Considerations

For UK and European organisations, WOPI data residency compliance is an increasingly important consideration. When a user edits a document through Office Online, the document content is transmitted to Microsoft’s servers for rendering and editing. Understanding where that processing occurs is essential for regulatory compliance.

CSPP Plus now supports the ComplianceDomainPrefix property, which allows hosts to specify which Microsoft regional data centre should process documents. For UK organisations subject to data sovereignty requirements — financial services firms, healthcare providers, government contractors — this capability ensures that document content is processed within approved jurisdictions.

When planning your migration, consider:

Which Microsoft data centres are acceptable for your compliance requirements (UK South, EU regions, etc.)
Whether different document categories have different residency requirements (public documents vs. regulated content)
How to configure the ComplianceDomainPrefix in your WOPI host to enforce the correct routing
Documentation requirements — regulators may ask you to demonstrate where document processing occurs

Planning Your Migration Project

Based on our experience delivering WOPI integrations, here is a practical project structure for migrating a legacy DMS to CSPP Plus.

Phase 1: Assessment and Planning (Weeks 1-3)

Audit the legacy DMS: storage architecture, document volumes, metadata schema, permission model, existing integrations
Select the architecture pattern (WOPI layer, hybrid, or full cloud migration)
Identify production domains and submit the allow-listing request to Microsoft
Define the WOPI host technology stack (.NET, Java, Node.js — the protocol is language-agnostic)
Establish the development environment and obtain dogfood environment access

Phase 2: Core WOPI Implementation (Weeks 3-8)

Implement the core WOPI endpoints: CheckFileInfo, GetFile, PutFile, Lock, Unlock, RefreshLock
Implement proof key validation
Implement the file URL generation and access token management
Build the integration layer between the WOPI host and the legacy storage backend
Test against the Microsoft dogfood environment

Phase 3: Advanced Features (Weeks 6-10)

Implement co-authoring support (concurrent editing, merge handling)
Implement the PostMessage API for communication between the Office editor and your host application’s UI
Add support for additional file operations: rename, delete, create new
Implement user identity mapping between your DMS user accounts and WOPI user identifiers
Configure data residency settings via ComplianceDomainPrefix

Phase 4: Testing and Compliance (Weeks 8-12)

Run the Microsoft WOPI Validator tool to verify protocol compliance
Perform load testing to validate performance under concurrent editing scenarios
Complete security testing, including proof key validation edge cases
Conduct user acceptance testing with representative document types and workflows
Prepare compliance documentation for CSPP Plus review

Phase 5: Go-Live (Weeks 10-14)

Confirm production domain allow-listing is active (submitted in Phase 1, typically ready by now)
Deploy the WOPI host to production infrastructure
Configure monitoring and alerting for WOPI endpoint health and performance
Execute a phased rollout — start with a pilot user group before enabling for all users
Monitor error rates, editing session durations, and user feedback during the rollout period

The total timeline is typically 12-14 weeks for a straightforward implementation, extending to 16-20 weeks for complex environments with hybrid storage, extensive permission models, or stringent compliance requirements.

Common Migration Scenarios

Scenario: SharePoint On-Premises to Cloud DMS with WOPI

Organisations running SharePoint Server on-premises often assume the only migration path is to SharePoint Online. While that is one option, it is not the only one. If your document management requirements have outgrown SharePoint’s model — or if you are building a SaaS product that needs embedded editing — implementing a custom WOPI host with cloud storage gives you more control over the user experience, the permission model, and the integration architecture.

Scenario: Bespoke DMS to Microsoft 365 Document Editing

Many organisations built bespoke document management systems 10-15 years ago, typically on .NET with SQL Server and Windows file shares. These systems work but cannot offer browser-based editing. Adding a WOPI host layer allows you to preserve the bespoke business logic, metadata schemas, and workflows that your users depend on while enabling Microsoft 365 editing capabilities.

Scenario: SaaS Platform Adding Document Editing

SaaS companies that manage documents as part of their platform — legal tech, construction management, insurance, healthcare — can differentiate their product by offering in-app Microsoft 365 editing. This is one of the most common CSPP Plus use cases we see at McKenna Consultants, and the Microsoft 365 document editing SaaS integration pattern is well-established.

Getting Started

The first step in any WOPI migration project is understanding your current document management architecture and defining your target state. Which documents need editing capabilities? Which architecture pattern is appropriate? What compliance and data residency requirements apply?

McKenna Consultants provides WOPI integration consultancy for UK organisations at every stage of the CSPP Plus journey — from initial assessment and architecture design through implementation, testing, and go-live. We have deep expertise in the WOPI protocol, proven experience with the CSPP Plus onboarding process, and the technical skill to integrate with legacy systems of all kinds.

If you are considering a migration from legacy document management to CSPP Plus, contact us to discuss your requirements and timeline.