1. Web application Open Platform Interface
WOPI
Web application Open Platform Interface

2. 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

3. 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

4. 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

5. 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.

6. Example flow: viewing a file

7. 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>

8. Discovery XML
<wopi-discovery> <net-zone name="external-https"> <app name="Word" favIconUrl=" checkLicense="true"> <action name="view" ext="docx" default="true" urlsrc=" </app> </net-zone> </wopi-discovery>

9. 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

10. 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

11. REST resource URIs Resource Description
Provides access to information about a file and allows for file-level operations.
Provides access to information about a folder and allows for folder level operations.
Provides access to operations that get and update the contents of a file.
Provides access to the files and folders in a folder.

12. 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
WOPI Client initiates GET to binary contents
WOPI Client renders file

13.
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": ,
"SHA256": "+17lwXXN0TMwtVJVs4Ll+gDHEIO06l+hXK6zWTUiYms=",
"Version": "GIYDCMBQGAVTAMB2GAYA====" }

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

15.
Here are some sample parameters…
CloseUrl
DownloadUrl
ReadOnly

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

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

18. 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

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

20. 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

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

22. 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

23. 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

24. 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

25. “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

26. 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

27. 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

28. Client-side Integration: PostMessage
Browser
Host Frame
App Frame

29. 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

30. 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

31. 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

32. Resources Office Online Server (TechNet) Cloud Storage Partner Program