Web application Open Platform Interface WOPI Web application Open Platform Interface

Overview WOPI is primarily a file I/O protocol Microsoft uses WOPI to integrate Office Online with… SharePoint Exchange Skype for Business Many 3rd parties also use WOPI to integrate with Office Online and Office Online Server WOPI is now being extended to allow integration between Office iOS apps and 3rd parties

Office Online Capabilities Viewing Word, PowerPoint, and Excel files Editing w/ real-time coauth of Word, PowerPoint, and Excel files (no Cobalt required) OneNote viewing and editing requires Cobalt

WOPI Integration Cloud Storage Partner Program Office Online Server Integration with Microsoft’s Office Online cloud service Requires formal agreement with Microsoft Commercial use tied to O365 subscriptions Office Online Server Allows customers to run Office Online on their own infratstructure EULA: viewing is free; editing is tied to SA licenses OR O365 subscriptions Other A 3rd party could write a WOPI application that would then work with properly designed WOPI hosts

The WOPI flow WOPI Host App SharePoint Browser Host Frame App Frame SPC2012 – IT Pro 4/28/2017 The WOPI flow SharePoint Host (WOPI Server) Browser WOPI Source Host Frame App Frame WOPI WOPI Source Access Token Office Online App (WOPI Client) © 2012 Microsoft Corporation. All rights reserved. Microsoft, Windows, and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries. The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

Example flow: viewing a file

WOPI Discovery Host App Host records bindings between file extensions and URLs Host (WOPI Server) App (WOPI Client) …/hosting/discovery <wopi-discovery> <net-zone name="external-https"> <app name="Word" … > <action name="view" ext="docx" default="true" urlsrc="..."/> </app> </net-zone> </wopi-discovery>

Discovery XML <wopi-discovery> <net-zone name="external-https"> <app name="Word" favIconUrl="https://.../FavIcon_Word.ico" checkLicense="true"> <action name="view" ext="docx" default="true" urlsrc="https://.../frame.aspx?<ui=UI_LLCC&><rs=DC_LLCC&>"/> </app> </net-zone> </wopi-discovery>

Verifying requests are from us: Proof Keys We sign every WOPI request with our private key We publish our public key in discovery Hosts can use the public key to validate that requests come from us

Conventions for <action /> Not a traditional XML schema Ignore the entry if its name is unknown Ignore the entry if one of its required capabilities is unknown

REST resource URIs Resource Description HTTP://server/<...>/wopi*/files/<id> Provides access to information about a file and allows for file-level operations. HTTP://server/<...>/wopi*/folders/<id> Provides access to information about a folder and allows for folder level operations. HTTP://server/<...>/wopi*/files/<id>/contents Provides access to operations that get and update the contents of a file. HTTP://server/<...>/wopi*/folder/<id>/children Provides access to the files and folders in a folder.

The view flow (again) WOPI Host Generates Client URL based on Discovery XML WOPI Host navigates a web page to Client URL WOPI Client initiates GET to WOPI Source URL HTTP://server/<...>/wopi*/files/<id> WOPI Client initiates GET to binary contents HTTP://server/<...>/wopi*/files/<id>/contents WOPI Client renders file

HTTP://server/<...>/wopi*/files/<id> Returns information about the file and permissions that the current user has relative to that file Contains information that the WOPI app may use to modify the user experience These are minimal response requirements for a CheckFileInfo request… { "BaseFileName": "Sample Document.docx", "OwnerId": "johndoe", "Size": 300519, "SHA256": "+17lwXXN0TMwtVJVs4Ll+gDHEIO06l+hXK6zWTUiYms=", "Version": "GIYDCMBQGAVTAMB2GAYA====" }

HTTP://server/<...>/wopi*/files/<id>/contents GetFile PutFile

HTTP://server/<...>/wopi*/files/<id> Here are some sample parameters… CloseUrl DownloadUrl ReadOnly

POST HTTP://server/<. >/wopi POST HTTP://server/<...>/wopi*/files/<id> with X-WOPI-Override PutRelativeFile GetRestrictedLink Lock RevokeRestrictedLink Unlock RefreshLock UnlockAndRelock ExecuteCellStorageRequest ExecuteCellStorageRelativeRequest DeleteFile ReadSecureStore

WOPI Additions New nouns ‘WOPI 2’ Bootstrapper WOPI Proper Native app authentication bridge New nouns Containers Ecosystem ‘WOPI 2’ Bootstrapper

Containers Can contain Files and other Containers Hierarchical arrangement assumed Why not ‘folders?’ Folders tend to imply physical storage; containers helps clarify that they can be virtual, rather than physical, constructs (e.g. a container could be the results of a particular search) Folders are used by OneNote; keep the namespaces separated

Container Operations CheckContainerInfo Enumerate children and ancestors Create child files and containers Rename/delete containers

Bootstrapper In order to initiate operations, native apps need authorization from the user Native apps will go through the OAuth 2.0 flow with a partner and retrieve an OAuth access token That token can be used to access operations on the Bootstrapper endpoint TL;DR - Allows an app with a valid OAuth 2.0 access token to retrieve WOPI access tokens for WOPI operations rather than have them provided to it by the host

Bootstrapper operations Initiates OAuth flow if not authed Provides a URL and WOPI token for the WOPI Ecosystem endpoint Provides basic user info

Important The Bootstrapper endpoint does not use WOPI tokens for auth It is a standard OAuth 2.0 token-protected endpoint All operations exposed on the Bootstrapper endpoint use OAuth 2.0 and initiate the OAuth 2.0 flow if not authed properly Thus, the Bootstrapper is important for native app WOPI use but it is not technically WOPI

Ecosystem endpoint Exists to help ‘navigate’ the WOPI namespace (aka ecosystem) Is not anchored to a specific file/container Clients with existing WOPISrc values can get to the Ecosystem via a GetEcosystem operation on either the Files or Containers endpoints

Ecosystem operations GetFileWopiSrc: Translates a partner-specific file/container URL into a WOPISrc value Useful when partner has a non-WOPI URL to a file that is commonly used (e.g. a share URL) GetRootContainer: Provides the ‘root container’ URL to kick start browsing the partner’s containers

“Browse from Root” sample call flow Call Bootstrapper Returns the Ecosystem endpoint URL and a WOPI token Call GetRootContainer using the URL/token from step 1 Returns the URL for the root container Call CheckContainerInfo using the URL/token from step 2 Returns user permissions for container Call EnumerateChildren using the URL/token from step 2 Returns direct children of root container Call CheckContainerInfo/EnumerateChildren as needed as user navigates

WOPI 2 Operations that were previously ‘missing’ in WOPI GetLock DeleteFile Increase supported lock size to 1024 ASCII characters (from 256) New SupportsWopi2 property in CheckFileInfo indicates host supports the above

Client-side Integration: PostMessage Allows hosts to plug into pieces of our UI Historically messages have been added ‘as needed’ with little review or consideration PostMessage is now a part of our public API, since it is necessary for many basic scenarios We will treat PostMessage like we do WOPI

Client-side Integration: PostMessage Browser Host Frame App Frame

Example flow: Share Host tells us they want to handle the ‘Share’ message in CheckFileInfo; FileSharingPostMessage = true When the Share button is clicked, we send the host the UI_Sharing message The host sends us the Blur_Focus message so we stop aggressively grabbing focus The host dims displays their Share UI When the user is done sharing, the host sends us the Grab_Focus message

Example messages Messages hosts can send Messages hosts can receive Blur_Focus Grab_Focus Host_PerfTiming Host_PostmessageReady Messages hosts can receive File_Rename UI_Close UI_Edit UI_FileVersions UI_Sharing

Host Communication: Three Ways Query string parameters Exposed as placeholder values on the urlsrc parameter in discovery CheckFileInfo Called on application boot, and periodically throughout a session PostMessage

Resources Office Online Server (TechNet) Cloud Storage Partner Program https://wopi.readthedocs.org