How to replace Office Online Server in SharePoint SE: WOPI binding step by step

To replace Office Online Server in SharePoint Server Subscription Edition, you point the farm's WOPI binding at a new WOPI client. SharePoint itself does not change: you export the current bindings, remove only the Office Online Server bindings, create new ones for the replacement and test with an ordinary user. The switch takes minutes, needs no reboot or IIS reset, and can be reversed with the same cmdlets.

This guide uses only standard SharePoint Server cmdlets, so it works for any WOPI client. Why the switch is needed at all is covered in our Office Online Server end-of-life guide.

What the WOPI binding does

SharePoint Server does not render Word, Excel, PowerPoint or PDF files itself. For each application, file extension and action (such as view or interactivepreview), it keeps a binding to a WOPI client. When a user opens a document, SharePoint sends the browser to the client named in that binding, together with a short-lived access token. The client then fetches the file from SharePoint and renders it.

Replacing Office Online Server therefore means replacing those bindings. Libraries, permissions and documents stay exactly as they are.

Before you start

Check these prerequisites before you touch the binding. Most failed switches trace back to one of them.

• Farm administrator rights and the SharePoint Management Shell, run as administrator on a SharePoint server in the farm.
• The new WOPI client is installed and reachable over HTTPS under a DNS name, for example wopi.contoso.local. Use a DNS name, never an IP address, and a name that every user's browser can resolve.
• Trusted certificates on both sides. The certificate of the WOPI client must be trusted by the SharePoint servers and by your users' browsers. If it comes from an internal CA, import the CA certificate into LocalMachine\Root on every SharePoint server and distribute it to clients by Group Policy. SharePoint's own certificate must be trusted by the WOPI client in the same way.
• HTTPS only. Do not use -AllowHTTP. Access tokens travel in these requests, and an HTTP binding sends them in clear text.
• The discovery endpoint answers. Open https://wopi.contoso.local/hosting/discovery from a SharePoint server. It must return HTTP 200 and an XML document listing the supported applications and actions.
• A test user who is not a system account. The farm account, the setup account and application pool accounts do not receive WOPI access tokens, so a test with them fails even when everything is configured correctly.

Plan the switch in a maintenance window. Between removing the old bindings and creating the new ones, documents cannot open in the browser, so run steps 2 and 3 back to back.

Step 1: record the current bindings and zone

Start by writing down exactly what is bound today. This export is your rollback plan.

Get-SPWOPIZone
Get-SPWOPIBinding | Select-Object Application, Extension, Action, ServerName, IsDefaultAction |
  Sort-Object ServerName, Application, Extension |
  Format-Table -AutoSize

Get-SPWOPIBinding | Select-Object Application, Extension, Action, ProgId, ServerName, IsDefaultAction |
  Export-Csv -Path C:\Wopi\bindings-before-switch.csv -NoTypeInformation

Keep the CSV file. It shows which server each binding points to, which matters if the farm has bindings for more than Office Online Server.

Step 2: remove only the Office Online Server bindings

Remove the bindings that point to your Office Online Server, and nothing else:

Remove-SPWOPIBinding -Server oos.contoso.local -Confirm:$false
Get-SPWOPIBinding | Select-Object Application, Extension, ServerName

Many guides use Remove-SPWOPIBinding -All:$true. Avoid it: it deletes every binding in the farm, including bindings for other WOPI applications you may rely on, and leaves you to rebuild them from memory. Targeting the server name removes exactly what you are replacing.

The second command should no longer list oos.contoso.local.

Step 3: create the new binding and set the zone

Create the bindings for the new WOPI client. SharePoint reads its discovery document and adds one binding per supported application, extension and action:

New-SPWOPIBinding -ServerName wopi.contoso.local
Set-SPWOPIZone -Zone "internal-https"

The zone tells SharePoint which URLs from the discovery document to use. internal-https fits farms where users and the WOPI client are on the internal network. If your farm uses another zone today, keep the value you recorded in step 1.

No reboot and no IIS reset are needed. The new bindings take effect immediately.

Optional: pilot one file type first

You do not have to switch everything at once. To start with Word documents only, for example, remove and recreate the bindings for a single extension:

Remove-SPWOPIBinding -Server oos.contoso.local -Application Word -Extension docx -Confirm:$false
New-SPWOPIBinding -ServerName wopi.contoso.local -Application Word -Extension docx

All other file types keep opening in Office Online Server until you switch them too. This is a low-risk way to run a pilot in production.

Step 4: verify the switch

Check the configuration first, then the user experience.

Get-SPWOPIBinding | Group-Object ServerName | Select-Object Name, Count
Get-SPWOPIZone

All bindings you expect should point to wopi.contoso.local. Then sign in as an ordinary user, not a system account, and work through this list:

1. Open a Word, an Excel and a PowerPoint file from a document library. Each should open in the browser instead of downloading.
2. Open a PDF, if your WOPI client handles PDF files.
3. Search for a document and hover over the result. The preview in the hover panel also comes from the WOPI client.
4. Open a document in every zone your users work in, for example both the internal and the extranet URL.
5. Check the browser's developer tools for blocked frames or certificate errors if a document does not open.

If something fails, the most common causes are an untrusted certificate, a DNS name that clients cannot resolve, or a test with a system account. Our security page describes how requests between SharePoint and Office Render Engine are authenticated.

After a certificate or key change

If the WOPI client's proof key is rotated later, refresh it in SharePoint so that signed requests keep validating:

Update-SPWOPIProofKey -ServerName wopi.contoso.local

You do not need this command for the initial switch.

Rollback: return to Office Online Server

Because the switch only changes bindings, rolling back is quick. Remove the new bindings by server name and recreate the Office Online Server bindings:

Remove-SPWOPIBinding -Server wopi.contoso.local -Confirm:$false
New-SPWOPIBinding -ServerName oos.contoso.local
Set-SPWOPIZone -Zone "internal-https"

Use the zone you recorded in step 1. Then compare the result with your export:

Get-SPWOPIBinding | Select-Object Application, Extension, Action, ServerName |
  Sort-Object ServerName, Application, Extension

If your farm had customised bindings, for example only some extensions bound to Office Online Server, recreate them from the CSV file with -Application and -Extension instead of binding every application at once. Rehearse the rollback once on a test farm, so that it is a known procedure when you need it.

Frequently asked questions

Do I need to restart SharePoint or IIS after changing the WOPI binding?

No. New and removed bindings take effect immediately. Users only need to reload the page.

Can I run Office Online Server and a replacement side by side?

Yes. Bindings are set per application and file extension, so you can move one file type at a time. You can also test the replacement on a separate farm before you touch production.

Why does the test work for me but not for my users?

You are probably testing with the farm account or another system account. These accounts do not get WOPI access tokens. Test with an ordinary user account, as described in step 4.

Does the new WOPI client need internet access?

That depends on the product. Office Render Engine runs entirely inside your network and makes no connection to the internet or to any cloud service.

Switching to Office Render Engine

Office Render Engine is an on-premises WOPI client built to replace Office Online Server for viewing. It uses exactly the binding steps above. Today it is view-only: Word, Excel, PowerPoint and PDF open in the browser and in search previews, but documents are edited in desktop Office. Our limitations page lists what it does not do yet.

Before a pilot we test your authentication setup with you, so that the switch in your farm follows a validated path.