Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/officedev/pnp-wopi

Patterns and Practices repo for Office Online integration via WOPI Host
https://github.com/officedev/pnp-wopi

Last synced: about 1 year ago
JSON representation

Patterns and Practices repo for Office Online integration via WOPI Host

Awesome Lists containing this project

README 

          
---

page_type: sample

products:

- office-365

languages:

- csharp

extensions:

  contentType: samples

  createdDate: 1/14/2016 6:35:35 AM

---

# PnP-WOPI

This repository contains an application that integrates with Office Online for viewing/editing Office documents. This type of integration classifies this application as a WOPI host. WOPI (Web Application Open Platform Interface) is a protocol for integrating with Office Online and is documented in detail at [https://wopi.readthedocs.org](https://wopi.readthedocs.org "https://wopi.readthedocs.org"). This sample illustrates many important patterns and practices for implementing a WOPI host, a number of which are outlined in this readme. 



> NOTE: You cannot simply clone and run this sample locally. Integrating with Office Online requires that your host domain is white-listed by Microsoft. The first step to white-listing a domain is to join the Cloud Storage Provider Program detail [HERE](http://dev.office.com/programs/officecloudstorage "HERE"). Additionally, a WOPI host must expose endpoints to the internet that Office Online can communicate with (read: localhost probably won't work).



## Solution Overview ##

This WOPI host sample is written in ASP.NET/C# with MVC for the user interface and Web API for the WOPI endpoints. Although it uses Azure AD for user identity, Azure AD has NOTHING to do with the WOPI integration. A WOPI host can use virtually any identity provider (or function anonymously). The sample stores files in Azure Blob Storage and file metadata in Azure DocumentDB (a NoSQL platform service similar to MongoDB). There a number of configuration values that should be updated in the web.config to support the identity and storage providers:



    

    

    

    

    

    

    

    

    

    

    

    

    

    

    

    



A WOPI host is composed of two primary components...a frame to host the Office Online renderings and endpoints that Office Online can call into to perform specific operations (ex: GetFile, PutFile, etc). Both of these components and their unique considerations are detailed below.



## WOPI Host Page ##

The WOPI host page for this sample is found in the **Home/Detail** view with logic in the **Detail** method of the **HomeController.cs**. This page can only be invoked with a WOPI action and a file id. The WOPI action includes details on how to reach Office Online for the desired action (ex: view, edit, etc). The file id is used to look up file details which placed in a form in the Detail view that is posted to the WOPI action URL. When invoked, the controller will also generate a user and file specific access token that is part of the POST to the WOPI action URL.



    

        

        

    

    

    

        var frameholder = document.getElementById("frameholder");

        var office_frame = document.createElement("iframe");

        office_frame.name = "office_frame";

        office_frame.id ="office_frame";

        frameholder.appendChild(office_frame);



		//Submit the form the WOPI action URL

        document.getElementById("office_form").submit();

    



Essentially, the WOPI Host Page hosts and posts data to a big IFRAME that renders Office Online.



## WOPI Endpoints ##

The WOPI endpoints should not use the default auth that is configured in Startup.Auth.cs. Remember, Office Online is what calls into these endpoints and it has no dependency on Azure AD. Office Online will pass an access token in the header of all WOPI requests (using the Authorization header). This is the exact same access token that the WOPI Host Page generated a posted to the WOPI action URL. To accomplish this from the same web application, the **WebApiConfig.cs** needs to ignore the default authentication:



	// Ignore AAD Auth for WebAPI...will be handled by WopiTokenValidationFilter class

	config.SuppressDefaultHostAuthentication();



The application also needs a **AuthorizeAttribute** to validate the access token on requests. This sample implements this in the **WopiTokenValidationFilter** class. The WebAPI routes are all configured with this filter as seen below. The **WopiSecurity** class contains methods to generate and validate our custom access tokens.



	[WopiTokenValidationFilter]

    [HttpGet]

    [Route("wopi/files/{id}")]

    public async Task Get(Guid id)

    {

        //Handles CheckFileInfo

        return await HttpContext.Current.ProcessWopiRequest();

    }



One of the challenges of implementing the WOPI endpoints with WebAPI is that most of the WOPI operations use the same few routes. Operations are instead determined by the header details included on requests. As such, the **filesController** has four generic endpoints that simply call a **ProcessWopiRequest** extension on the HttpContext:



    [WopiTokenValidationFilter]

    public class filesController : ApiController

    {

        [WopiTokenValidationFilter]

        [HttpGet]

        [Route("wopi/files/{id}")]

        public async Task Get(Guid id)

        {

            //Handles CheckFileInfo

            return await HttpContext.Current.ProcessWopiRequest();

        }



        [WopiTokenValidationFilter]

        [HttpGet]

        [Route("wopi/files/{id}/contents")]

        public async Task Contents(Guid id)

        {

            //Handles GetFile

            return await HttpContext.Current.ProcessWopiRequest();

        }



        [WopiTokenValidationFilter]

        [HttpPost]

        [Route("wopi/files/{id}")]

        public async Task Post(Guid id)

        {

            //Handles Lock, GetLock, RefreshLock, Unlock, UnlockAndRelock, PutRelativeFile, RenameFile, PutUserInfo

            return await HttpContext.Current.ProcessWopiRequest();

        }



        [WopiTokenValidationFilter]

        [HttpPost]

        [Route("wopi/files/{id}/contents")]

        public async Task PostContents(Guid id)

        {

            //Handles PutFile

            return await HttpContext.Current.ProcessWopiRequest();

        }

    }



Most of the WOPI logic exists in the **WOPIExtensions.cs** and **WOPIUtils.cs** files. The **WOPIExtensions.cs** file contains extension methods for each WOPI operation and the **WOPIUtils.cs** contains utility methods for doing things such as WOPI discovery (which lists all the actions and proof keys for the WOPI integration), validating WOPI proof (ie - proving that the WOPI request actually came from Office Online), and a number of important WOPI constants (like the numerous custom headers WOPI uses).



## Join the Microsoft 365 Developer Program



Join the [Microsoft 365 Developer Program](https://aka.ms/m365devprogram) to get resources and information to help you build solutions for the Microsoft 365 platform, including recommendations tailored to your areas of interest.



You might also qualify for a free developer subscription that's renewable for 90 days and comes configured with sample data; for details, see the [FAQ](https://learn.microsoft.com/office/developer-program/microsoft-365-developer-program-faq#who-qualifies-for-a-microsoft-365-e5-developer-subscription-).



---



This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.