43
Office Online Integration Documentation, Release 2016.01.27
Following these steps will ensure that the in-application Edit button is displayed. When clicked, this button will
navigate the user to the HostEditUrl provided for the binary file, which will in turn begin the conversion process and
eventually redirect the user to the HostEditUrl forthe newly converted document.
Hosts may optionally handle the in-application Edit button themselves by setting theEditModePostMessageproperty
to true and handling theUI_Edit PostMessage.
1.19.2 Customizing the conversion process
In the basic conversion process,Office Online will create a new file each time a user attempts to edit a file in a binary
file format. For example,considerthis scenario:
1. A user opens a binary file named File.doc in the Office Online viewer.
2. The user clicks the Edit button in the Office Online viewer.
3. The conversion process is started,andOffice Online callsPutRelativeFileonthehost, creatinga newlyconverted
file, File.docx.
4. The user edits the newly converted document, then ends the editing session.
5. Later,the userreturns and opens the original binary file,File.doc, in the Office Online viewer.
Atthis point, the user maybe confusedas towhy the changes made earlierare not in the document. Ifthe userattempts
toedit the file again,Office Online willagain convert it and createa second converted file,forexample File1.docx.
This can be very confusing for users depending on how the userexperience within the host UI is designed. Thus,it is
importantto considerhow to manage userconfusionaround converteddocuments. There are threebasiccustomization
options that hosts can employ to help manage this.
First, the host can choose to display some UI to the user prior to beginning the conversion process. Because hosts
ultimately control when theconvert action is invoked, a host could choose to display a notification message when
auser attempts to edit a binary document, informing them that the document will be converted. This can also apply
to the in-application Edit button by setting theEditModePostMessageproperty to true and handling theUI_Edit
PostMessage.
Second,thehostcan choosetohandle converteddocuments ina unique way,by handling thePutRelativeFileoperation
differently whencalled fromtheconversion flow. The X-WOPI-FileConversionheadertells hosts when the operation
is being called fromthe conversion flow, so the host can choose how best to handle those requests.
Finally, the host can control where the user is navigated after conversion is complete. Office Online navigates to the
HostEditUrlthatisreturnedinthePutRelativeFileresponse,whichthehostcontrols.Thus,hostscancustomizewhere
the userlands after the conversionis finished. This allows hosts to opt not tosend the userdirectlyto the Office Online
editor, but to any URL they wish. For example, a host may redirect the user to an interstitial page that informs them
their document has been converted.
The following are some examples illustrating how these options can be used by hosts to change the user experience
around file conversion. Note that these examples are not meant to be exhaustive,and that hosts may opt to customize
the conversion process and flow in ways not described here.
Example 1
In the following example, the host helps the user understand the conversionprocess by naming the convertedfile such
that it is clearthat it was converted froma binary file.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
1.19. Editing binary document formats
59
RasterEdge Product Renewal and Update 4. Order email. Our support team will send you the purchase link. HTML5 Viewer for .NET; XDoc.Windows Viewer for .NET; XDoc.Converter for .NET; XDoc.PDF for .NET;
adding hyperlinks to pdf documents; pdf hyperlinks
39
Office Online Integration Documentation, Release 2016.01.27
3. The host creates a new file as part of the PutRelativeFile request and appends (Editable) to the name of the
file.
4. The user is navigated to a page that allows them to edit the newly converted file in Office Online.
Example 2
In the following example,the host wishes to hide the conversion process from the user to provide the most frictionless
experience possible.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
3. Rather than create a new file, the host chooses to add the converted file as a new version to the existing binary
file.
4. The user is navigated to a page that allows them to edit the newly converted file in Office Online.
5. The user can restore the binary version ofthe file by using the ‘version history’ features within the host.
Note: This approach may not be feasible for all hosts, depending on how file metadata and versions are handled
within their system. However,it does offerthe following benefits:
• The user only ever sees a single document both before and after the document is converted.
• Since there is always only a single document, the user always finds the ‘right’ document. That is, if the user
editedthefile -whichis likely since theyinvoked theconversion process byattempting to edita binary document
-then when they open the file a second time, their previous edits will be there, just as they expect.
Example 3
In the following example,the hosthas deemedit important to informusers explicitly about the conversion process and
its possible side effects.
1. A user selects a binary file in the host UI and chooses to edit it using Office Online.
2. The host displays a notification message with the following text:
In order to edit File.doc, it must be converted to a modern file format. If the document doesn’t look
the same after it’s converted, don’t worry- you canalways getback to the original file if you need to.
The user can cancel the conversion operation or choose to continue with it.
3. Ifthe userchooses to continue, the host navigates them to a page that invokes theconvert action on the file.
4. The conversion process is started, and Office Online callsPutRelativeFilewith the converted document content.
5. The host returns a special URL in theHostEditUrlproperty in the PutRelativeFile response. Office Online
navigates the userto that URL once the conversion is complete.
6. The user lands on the URL specified by the host, and sees the following message:
Your file, File.doc, has been converted to a new file, File.docx. The new file is in a modern file
format, and the file extension has changed. If you don’t need the original file any more, you can
delete it.
The message includes a button that the user can use to delete the original file immediately if they wish.
7. Once the user clicks OK, they’re navigated to a page that invokes theedit action on the converted file.
60
Chapter 1. How to read this documentation
5
Office Online Integration Documentation, Release 2016.01.27
Figure 1.14: Example conversionnotification message
Figure 1.15: Example conversion completed message
1.19. Editing binary document formats
61
37
Office Online Integration Documentation, Release 2016.01.27
Variant 3.1: Display post-conversion message in the Office Online UI
In steps 5and 6, rather than navigating the usertoan interstitial page,the host may choose toappend some parameters
to the standard HostEditUrl. Then, when that HostEditUrl is navigated to, the host page can use the parameters that
were added to the URL to determine that the dialog described in step 6 should be displayed. The host candisplay that
notification above the Office Online editor frame. This is similar to what hosts do when handling theUI_Sharing
PostMessage.
Tip: Hosts must ensure that they properly use theBlur_Focus andGrab_Focus messages when drawing UI
over the Office Online frame.
1.20 Verifying that requests originate from Office Online by using
proof keys
When processing WOPI requests from Office Online, you might want to verify that these requests are coming from
Office Online. To do this,youuse proof keys.
Office Online signs every WOPI request witha private key. The corresponding public key is available in the proof-key
element in the WOPI discovery XML.The signature is sent with every request in the X-WOPI-Proof and X-WOPI-
ProofOldHTTP headers.
The signature is assembled from information that is available to the WOPI host when it processes the incoming WOPI
request. To verify that a request came fromOffice Online,you must:
• Create the expected value of the proof headers.
• Use the public key provided in WOPI discovery to decrypt the proof provided in the X-WOPI-Proof header.
• Compare the expected proof to the decrypted proof. Iftheymatch, the request originated fromOffice Online.
• Ensure that the X-WOPI-TimeStamp header is no more than 20 minutes old.
Note: Requests to theFileUrlwill not be signed. The FileUrl is used exactly as provided by the host, so it does not
necessarily include the access token, which is required to construct the expected proof.
Tip: TheOfficeOnlineGitHubrepositorycontains aset ofunitteststhathosts canadapt toverifyproof keyvalidation
implementations. SeeProofkeyunittestsfor more information.
1.20.1 Constructing the expected proof
To constructthe expected proof, you mustassemble a byte array consisting of the access token, the URL ofthe request
(in uppercase),and the value of the X-WOPI-TimeStamp HTTP header from the request. Each ofthese values must
be converted toa byte array. In addition,you must include the length, in bytes, ofeach ofthese values.
To convert the access token and request URL values, which are strings, to byte arrays, you must ensure the original
strings are in UTF-8 first, then convert the UTF-8 strings to byte arrays. Convert the X-WOPI-TimeStamp header to
along and then into a byte array. Do not treat it as a string.
Then, assemble the data as follows:
• 4 bytes that represent the length,in bytes, of the access_token on the request.
62
Chapter 1. How to read this documentation
82
Office Online Integration Documentation, Release 2016.01.27
• The access_token.
• 4 bytes that represent the length, in bytes, of the full URL of the WOPI request, including any query string
parameters.
• The WOPIrequest URL in all uppercase. All query string parameters on the request URL should be included.
• 4 bytes that represent the length,in bytes, of the X-WOPI-TimeStamp value.
• The X-WOPI-TimeStamp value.
The following C# code snippet illustrates the construction ofan expected proof.
Code sample 1.10: Sample code fromProofKeyHelper.cs
62
public bool Validate(ProofKeyValidationInput testCase)
63
{
64
// Encode values from headers into byte[]
65
var accessTokenBytes = = Encoding.UTF8.GetBytes(testCase.AccessToken);
66
var hostUrlBytes = = Encoding.UTF8.GetBytes(testCase.Url.ToUpperInvariant());
67
var timeStampBytes = EncodeNumber(testCase.Timestamp);
68
69
// prepare a list that will be used to combine all those arrays together
70
List<byte> expectedProof = new List<byte>(
71
4 + accessTokenBytes.Length +
72
4 + hostUrlBytes.Length h +
73
4 + timeStampBytes.Length);
74
75
expectedProof.AddRange(EncodeNumber(accessTokenBytes.Length));
76
expectedProof.AddRange(accessTokenBytes);
77
expectedProof.AddRange(EncodeNumber(hostUrlBytes.Length));
78
expectedProof.AddRange(hostUrlBytes);
79
expectedProof.AddRange(EncodeNumber(timeStampBytes.Length));
80
expectedProof.AddRange(timeStampBytes);
81
82
// create another byte[] from that list
83
byte[] expectedProofArray = = expectedProof.ToArray();
84
85
// validate it against current and old keys in proper combinations
86
bool validationResult =
87
TryVerification(expectedProofArray, testCase.Proof, _currentKey) ||
88
TryVerification(expectedProofArray, testCase.OldProof, _currentKey) ||
89
TryVerification(expectedProofArray, testCase.Proof, _oldKey);
90
91
// TODO:
92
// in real code you should also check that TimeStamp header is no more than 20 minutes old
93
// but because we're using predefined test cases to validate that the method works
94
// we can't do it here.
95
return validationResult;
96
}
1.20.2 Retrieving the public key
Office Online provides two different public keys as part ofthe WOPI discovery XML: the current key and the old key.
Two keys are necessary because the discovery data is meant to be cached by the host, and Office Online periodically
rotates the keys it uses to sign requests. When the keys are rotated, the current key becomes the old key, and a new
currentkeyis generated. This helps tominimizetheriskthata host does not haveupdatedkey information fromWOPI
discovery when Office Online rotates keys.
1.20. Verifying that requests originate from Office Online by using proof keys
63
56
Office Online Integration Documentation, Release 2016.01.27
Both keys are represented in the discovery XML in two different formats. One format is for WOPI hosts that use the
.NET framework. The otherformat can be imported in a variety of different programming languages and platforms.
Using .NET to retrieve the public key
If your application is built on the .NET framework, you should use the contents of the value and oldvalue attributes
of the proof-key element in the WOPI discovery XML. These two attributes contain the Base64-encoded public keys
that are exported by using theRSACryptoServiceProvider.ExportCspBlobmethod ofthe .NET Framework.
To import this key in your application,you must decode it from Base64 then import it by using theRSACryptoServi-
ceProvider.ImportCspBlobmethod.
Using the RSA modulus and exponent to retrieve the public key
For hosts that don’t use the .NET framework, Office Online provides the RSA modulus and exponent directly. The
modulus and exponentofthe current keyare foundin the modulus andexponentattributes ofthe proof-key element in
the WOPI discovery XML. The modulus and exponent of the old key are found in the oldmodulus and oldexponent
attributes. All fourof these values are Base64-encoded.
The steps to import these values differbased onthe language, platform, and cryptography APIthat you are using.
The following example shows how to import the public key by using the modulus and exponent in a Python program
using the PyCrypto library.
1
from base64 import b64decode
2
from Crypto.PublicKey import t RSA
3
from Crypto.Util import asn1
4
5
def generate_key(modulus_b64, exp_b64):
6
mod = int(b64decode(modulus_b64).encode('hex'), 16)
7
exp = int(b64decode(exp_b64).encode('hex'), 16)
8
seq = asn1.DerSequence()
9
seq.append(mod)
10
seq.append(exp)
11
der = seq.encode()
12
return RSA.importKey(der)
13
14
# proof_key_attributes is from the discovery XML
15
key = generate_key(proof_key_attributes['modulus'], proof_key_attributes['exponent'])
1.20.3 Verifying the proof keys
Afteryouimport the key, you can use a verificationmethod provided by your cryptography library to verify incoming
requests were signed by Office Online. Because Office Online rotates the current and oldproof keys periodically, you
have to check three combinations of proof key values:
• The X-WOPI-Proof value using the current public key
• The X-WOPI-ProofOld value usingthe current public key
• The X-WOPI-Proof value using the old public key
If anyone ofthe values is valid, the request was signed by Office Online.
The following example shows how toverify one of these combinations in .NET.
64
Chapter 1. How to read this documentation
68
Office Online Integration Documentation, Release 2016.01.27
1
private static c bool TryVerification(byte[] expectedProof, byte[] signedProof, , byte[] publicKeyToTry, , int keySize)
2
{
3
using (RSACryptoServiceProvider rsaAlg = new w RSACryptoServiceProvider(keySize))
4
{
5
try
6
{
7
rsaAlg.ImportCspBlob(publicKeyToTry);
8
bool result = = rsaAlg.VerifyData(expectedProof, , "SHA256", signedProof);
9
return result;
10
}
11
catch(Exception e)
12
{
13
return false;
14
}
15
}
16
}
The following example shows how toverify one of these combinations in Python using the PyCrypto library.
1
from base64 import b64decode
2
from Crypto.Hash import SHA256
3
from Crypto.Signature import t PKCS1_v1_5
4
5
def try_verification(expected_proof, signed_proof, , public_key):
6
verifier = PKCS1_v1_5.new(public_key)
7
h = SHA256.new(expected_proof)
8
return verifier.verify(h, signed_proof)
1.20.4 Troubleshooting proof key implementations
If you are having difficulty with your proof key verification implementation, here are some common issues that you
should investigate:
• Verify you’re converting the URL to uppercase.
• Verify you’re including any query string parameters on the URL when transforming it for the purposes of
building the expected proof value.
• Verify you’re using the same encoding for any special characters that may be in the URL.
• Verify you’re using an HTTPS URL if your WOPI endpoints are HTTPS. This is especially important if you
have SSL termination inyour network prior to yourWOPIrequesthandlers. In this case,theURL Office Online
will use tosign the requests will be HTTPS, butthe URL yourWOPIhandlers ultimatelyreceive will be HTTP.
If you simply use the incoming request URL your expected proof will not match the signature provided by
Office Online.
In addition, use theProofkeyunitteststo verify your implementation with sample data.
1.21 Considerations for security and privacy
1.21.1 Office Online and customer data
There are two classes of customer data that flow through Office Online servers: user metadata and customer content
(documents, presentations,workbooks, and notebooks).
1.21. Considerations for security and privacy
65
24
Office Online Integration Documentation, Release 2016.01.27
User metadata
User metadata consists of URLs,email addresses, user IDs, etc. This data lives in memory and travels back and forth
betweenOffice Online and the WOPI host through HTTPS. Office Online goes to great lengths to scrub all personally
identifying information (PII) fromits logs. This is regularly audited to ensure Office Online is compliant with several
different privacy standards (such as FedRamp in the USA).
Customer content
In the case of customer content, Office Online retrieves it from the host in orderto renderit for viewing orediting. In
the image below you can see how WOPI is used to fetch content from the host and send content changes to the host
(ContosoDrive in this case).
Figure 1.16: WOPI protocol workflow
With the exception of caching (discussed below), it is reasonable to say that customer content only lives on Office
Online servers during a usersession. That is, a usercan reasonably expect that when they end an editing session, their
content will no longer live anywhere on Office Online servers once it has been saved to the host. The key exception
here is the Office Online viewing cache.
The Office Online viewing cache
In order to optimize view performance for PowerPoint Online and Word Online, Office Online stores rendered docu-
ments in a local disk cache. This way, if more than one person wants to view a document, Office Online only has to
fetch it and render it once. It is important tonote that a complete removal of the cache would significantly degrade the
customer experience formany users and dramatically increase the cost ofrunning Office Online.
Documents in the cache are indexed using aSHA256hash that is generated based on the contents of the file (or some
other unique attribute of the file). No user information is used to index the file. On every request for a file, if the
66
Chapter 1. How to read this documentation
Documents you may be interested
Documents you may be interested
