Why a Collabora Online WOPI host allow list matters and when to set one
A WOPI host allow list limits which storage platforms may ask your Collabora Online server to open and edit documents. Without one, any system that can reach the server and speak the WOPI protocol can request document sessions, so a production server should always have an explicit list of trusted hosts. The need is strongest when one server serves several platforms, when the server is shared between departments or customers, or when it sits on a network reachable from more than the intended applications. WOPI, the Web Application Open Platform Interface, is the handshake between a storage host and an editor. The host, such as Nextcloud, tells the editor where a file lives and who is asking, and the editor fetches the file through the host's own endpoints. Collabora lists many WOPI integrations, including Nextcloud, ownCloud, Seafile and others on its Collabora Online product page, so the list must reflect the hosts you actually run. Start from an inventory of every platform, test instance and staging system that will call the server, and treat anything not on that inventory as unknown.
Set the list before go-live, not after an incident. Decide who owns the list, how new hosts are requested and approved, and how removed platforms are taken off. Confirm the exact host names and URL forms each platform sends with your own test environment, because a mismatch either blocks legitimate editing or leaves a gap. The allow list is one control, not a complete boundary: it works alongside network restrictions, TLS, proof keys and access tokens covered in the sibling sections of this group. Plan to review the list whenever you add an integration, retire a platform or change a hostname.
How the allow list, aliasgroups and Nextcloud settings fit together
A document open passes through three components, and each one makes its own check. Nextcloud, acting as the WOPI host, gives the browser a link to the Collabora server. The browser then loads the editor from that server, and the Collabora server calls back to Nextcloud over WOPI to read file information and content and to save changes. Each callback is a place where an unknown or mismatched host can be refused, so the allow list only works when every hop agrees on names, addresses and protocol.
- Browser to Collabora server: the editor loads from the server URL that Nextcloud is configured with, so that URL must be reachable from users' networks.
- Collabora server to WOPI host: the server requests file metadata and content from the storage address it has been told to trust, and it refuses hosts it does not know.
- WOPI host to Collabora server: Nextcloud accepts WOPI requests from Collabora, and the administration manual recommends limiting those requests to the Collabora server addresses.
- Name and address agreement: the host name the browser uses, the name the server sees and the address that reaches Nextcloud can differ when proxies or internal DNS are involved.
- Protocol agreement: an HTTP and HTTPS mismatch between the server URL and the Nextcloud installation can break sessions or weaken the check.
Before changing anything, trace one document open from start to finish and write down the host name, address and protocol seen at each hop.
The Collabora server decides which storage hosts it will serve. Those decisions live in its configuration file, coolwsd.xml, where WOPI host entries name the storage hosts allowed to call the server, and aliasgroups let one storage host appear under more than one name, such as an internal address and a public one. Confirm the exact section names and syntax against the documentation for your version, because the layout can change between major branches.
- WOPI host entries: list only the storage hosts that should use this server, and leave out broad patterns that would admit anything on a network.
- Aliasgroups: add each name a storage host is reached by so legitimate traffic is not refused, and remove names that no longer exist.
- Protocol per entry: match the scheme each entry uses to the scheme the storage host actually serves, and avoid listing HTTP names on a production server.
- Restart after edits: confirm the new settings are active by checking the logs after a restart, because a small typo can leave the old list in place.
- Refusal logs: watch for messages about unknown hosts during testing, since they confirm the check is working and show which names still need an entry.
Check that a host you did not list is refused, and that every host you did list still opens documents.
On the Nextcloud side, the Office integration tells users where the Collabora server is and controls which users may open or edit documents. The Nextcloud administration manual covers these settings in its Office configuration section. Its guidance is to restrict WOPI requests to the IP addresses of the Collabora servers, and to use the same protocol, preferably HTTPS, for the Collabora server URL as for the Nextcloud installation. Nextcloud-side restrictions reduce what a compromised account can do, but they do not replace the server-side allow list.
- Collabora server URL: enter the address users' browsers will reach, using HTTPS, and make sure it matches the scheme Nextcloud itself uses.
- Address restriction: follow the manual to limit incoming WOPI requests to the Collabora server addresses, and update that list whenever those addresses change.
- Group limits: decide which groups may use the editor and which groups may only view documents without editing them.
- Trusted proxies: if Collabora traffic reaches Nextcloud through a proxy, check how Nextcloud's trusted proxy setting affects the addresses it sees and logs.
- Version alignment: keep the Office app compatible with your Nextcloud release, and retest the allow list after every upgrade.
Test from the Nextcloud side as a permitted user and as a user outside the permitted groups, and confirm each result matches your policy.
Most production deployments place a reverse proxy in front of the Collabora server to terminate TLS and route traffic. The proxy changes what the server sees. Any address-based restriction applies to the address that connects to the server, which is the proxy when the proxy sits in front. Decide where each check happens, then configure the other layers to match, so that a rule written at one layer is not quietly bypassed at another.
- TLS termination: if the proxy terminates TLS, keep the external scheme HTTPS in both Nextcloud and the Collabora server URL, and verify the forwarded protocol headers the server receives.
- Address checks: an address restriction on the Collabora server sees the proxy's address, so place source filtering where the real WOPI host address is visible, or on the proxy itself.
- WebSocket support: confirm the proxy passes the connection upgrade that editing sessions need, or sessions will fail in ways that look like allow list errors.
- Routing for scale: when several Collabora servers sit behind a load balancer, route by the WOPISrc parameter so all users of one document reach the same server, as the Helm chart documentation describes for Kubernetes.
- Header handling: review which forwarding headers the proxy accepts from clients, and strip any it should not trust.
Send a request from an unknown host through the full path and confirm the refusal happens at the layer you intended.
Allow list options and when each one fits
This table compares four ways to restrict which storage hosts can use a Collabora Online server, plus the Nextcloud group limits that control who may edit. Read each row for the setup it suits and the risk it carries, then combine layers rather than relying on one.
| Option | Fits best when | Main risk | Confirm before relying on it |
|---|---|---|---|
| Single exact host entry | One Nextcloud instance on a stable hostname serves all editing traffic | Breaks silently when the hostname, DNS record or reverse proxy name changes | The exact WOPI host key names for your Collabora version |
| Aliasgroups for several hosts | Several WOPI hosts or a Nextcloud cluster behind one name must be accepted | Wildcards or broad patterns admit hosts you never intended to trust | The aliasgroup syntax and whether your version matches hostnames by pattern |
| IP-based restriction at the network or proxy | The Nextcloud servers have fixed egress addresses you can list | Hostnames that resolve to changing addresses, or NAT and load balancers hiding the true source | Which address Collabora sees behind your proxy and whether forwarded headers are trusted |
| Nextcloud group restriction for editing | Only some users should open or edit documents in Nextcloud Office | Controls who uses the editor, not which servers may connect, so it does not block an unknown host | Group names and whether view-only access is enforced for your Nextcloud Office app version |
| Combined layers | Regulated or multi-tenant setups where a single control is not enough to show intent | More configuration to keep in sync during upgrades, DNS changes and certificate rotation | A test plan that covers every layer, including a refused request from an unlisted host |
Setting up the WOPI host allow list step by step
This sequence turns a list of approved storage hosts into a Collabora Online configuration that refuses every other WOPI host, with checks at each stage so you can confirm the restriction works before users depend on it.
Inventory every WOPI host and its protocol
Before touching any configuration, list every platform that will send documents to your Collabora Online server. For each one, record the exact host name, the port, the URL scheme (HTTP or HTTPS) and the network address or addresses it uses to reach Collabora. Include test, staging and disaster recovery instances, because a missing entry usually surfaces only when someone opens a document on that instance. The output is a signed-off inventory owned by the platform team, with one row per WOPI host. Confirm each row with the application owner rather than copying it from an old configuration file.
Define aliasgroups and WOPI host entries
Edit the Collabora Online configuration file, which is typically
coolwsd.xmlin the installation's configuration directory, and set thestorage.wopisection. Add onehostentry per approved WOPI host using the inventory, and setstorage.wopi[@allow]to true. Where a host is reachable under several names, define them underaliasgroupentries so each alias is listed explicitly. Leave the default for unknown hosts as refusal. Do not add wildcard patterns unless your inventory justifies them, and keep the file under change control. The check is that a configuration validation or a restart reads the file without error, and the entries appear in the effective settings when you query the server's configuration.Align the Nextcloud Office connector and server URL
In Nextcloud, open the Office settings and set the Collabora Online server URL. Use the same protocol that Nextcloud uses to reach itself, and prefer HTTPS as the Nextcloud administration manual recommends. A protocol mismatch between the two sides causes failures that look like allow list errors, so check both at once. Confirm that the groups allowed to use the editor and to edit are set as your access policy requires. The check is that the connector reports the server as reachable and that a test document opens over the same scheme you recorded in the inventory.
Restrict WOPI requests to Collabora server addresses
Where your network allows it, configure the Nextcloud side so that WOPI requests come only from the IP addresses of your Collabora servers, as the Nextcloud administration manual recommends. Apply the same restriction at the firewall or reverse proxy so that other sources cannot reach the WOPI endpoints. Record the addresses you permit and who approves changes to them, especially when servers sit behind a load balancer or change address after a rebuild. The check is that a request from an address outside the list is refused, which you test from a machine that is not a Collabora server.
Restart services and reload configuration
Restart the Collabora Online service so the modified configuration takes effect, and reload the Nextcloud configuration or caches as your deployment requires. Restarting is necessary because changes to the WOPI settings are not picked up by simply opening new documents. Make the change in a staging environment first when one exists, and keep a copy of the previous configuration so you can roll back. The check is that the service starts cleanly, stays running after the restart and returns its normal status response.
Check the server logs for allow list decisions
Open a document from each approved WOPI host and confirm that it loads, then review the Collabora Online server logs for the entries that show each request being accepted. Look for warnings about hosts that are not in the allow list and note any that appear for hosts you did not intend to include. Trace each unexpected entry back to the inventory before changing the configuration again. The check is a log record for every approved host and no accepted request from a host that is absent from your inventory.
Test that unknown hosts are refused
Using a test WOPI client or a host that is not in the inventory, send a request that names a storage host outside the allow list. The request should be refused, and the server log should record the refusal. Repeat the test from an address that is not in the Collabora IP restriction list to confirm the network control separately. Document the test cases, the expected result and the observed result, and keep them with the configuration so the test can be rerun after each upgrade or change. The check is a refusal for every unlisted host in the test set and a recorded result for each case.
How to test that unknown hosts are refused
Test refusal from an address that is not on the list before you trust the configuration. Pick a test host outside the approved set, for example an illustrative storage host at 203.0.113.50 that Nextcloud does not serve, and send it a WOPI request to the Collabora server: a CheckFileInfo call against a file ID, or a full open attempt from a browser session that the test host would make. The request should fail and no document should load. Record the status code, the response body and the time of the attempt. The exact refusal behavior (status code, message and whether the request is rejected at the reverse proxy or inside coolwsd) depends on the Collabora version and on your ingress, so confirm the expected result against the release you run rather than against this page.
Confirm that approved hosts still open documents. A allow list that blocks everything passes the refusal test and still breaks the product, so run the same open flow from the Nextcloud server and from a real user session in each approved hosting domain. Open a .docx, a .xlsx and a .pptx, edit one cell or paragraph, and confirm the change saves. Check that the WOPISrc value in the request matches the host name you listed in aliasgroups or the WOPI host settings, including the scheme and port if you set them. Keep the results in the change record with the Collabora and Nextcloud versions, so a later failure can be traced to a specific change.
Read the server log for both the refusal and any allow list warnings. Check the coolwsd log for entries that name the rejected host and for warnings about the allow list at startup, since a misspelled alias can silently remove a legitimate host. Compare what the log shows with the Nextcloud side: the admin settings for Nextcloud Office should show the Collabora URL you expect, and WOPI requests should come only from the Collabora server addresses you allowed. Repeat this whole plan after every change to the allow list, after changing the Collabora URL or certificates, and after every Collabora or Nextcloud upgrade, because log wording and default behavior can change between releases.
Security and operational risks of a loose allow list
A WOPI host allow list is only as good as its entries and the way they are maintained. The six risks below show where a loose or stale list lets the wrong storage host reach your Collabora Online server, or where a tight list breaks editing for legitimate users. Each card pairs the risk with a mitigation you can check in your own environment.
Overly broad aliasgroups
An aliasgroup that matches a wildcard or a whole domain admits every host under it, including hosts you never onboarded. Review each aliasgroup entry and replace broad patterns with the exact hostnames your Nextcloud or other WOPI hosts use. Confirm in the server configuration that no entry admits more than one intended host, and document the owner of each entry so changes have a name attached.
Hostnames that change
Storage hosts often move during DNS changes, reverse proxy rebuilds, or certificate renewals. When the hostname in the allow list no longer matches the one Nextcloud presents, editing fails for users and the temptation is to add a wildcard to restore service. Record the canonical hostname in your change process, and test the allow list after every DNS or ingress change so a rename is caught before users report it.
IP restrictions behind NAT or load balancers
The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers. Behind NAT, a shared egress address, or a load balancer, the address Collabora sees may not be the one you expected, so IP rules either block legitimate traffic or match more sources than intended. Confirm which address appears in the logs for a real request through your actual network path before relying on an IP rule, and combine it with hostname checks rather than trusting either alone.
HTTP-only Collabora URLs
The Nextcloud documentation recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. If either side runs over plain HTTP, requests and document content can be read or altered on the network, and mixed protocols cause connection failures that teams often fix by loosening checks. Verify that the Nextcloud Office URL and the WOPI host configuration both use HTTPS with valid certificates before the allow list is considered complete.
Drift from unreviewed new hosts
Each new WOPI integration adds an entry, and entries added to fix a single outage are rarely removed afterward. Over time the list accumulates decommissioned hosts, test systems and duplicates that still pass the check. Require a written request and an owner for every new host, schedule a quarterly review that compares the list to your current integration inventory, and remove entries for any system that no longer exists.
Reliance on a single control
An allow list limits which hosts can call the server, but it does not authenticate documents, users or access tokens, and it does not stop a compromised but allowed host from misusing the server. Treat the allow list as one layer alongside proof keys, access token validation, TLS, network segmentation and the Nextcloud group limits that control who can edit. Test each layer separately, and check that a request from an unknown host fails even if the other controls are configured correctly.
Questions teams ask before configuring the WOPI host allow list
Does the WOPI host allow list alone secure a Collabora Online server?
No. The allow list limits which storage hosts can ask the server to open documents, which closes one obvious path for unknown hosts, but it does not by itself protect the server from malicious documents, weak TLS, exposed admin endpoints or unpatched releases. Treat it as one control among several. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers, and the same protocol, preferably HTTPS, should be used for the Collabora server URL as for the Nextcloud installation. Pair the allow list with those network and TLS settings, proof key verification and a patching routine, then test each layer separately.
How long does allow list configuration take?
The configuration itself is short, but the duration depends on the work around it. The main drivers are the number of storage hosts that need access, how many of them sit behind different domains or aliases, whether your network controls allow you to restrict source addresses at the firewall or reverse proxy, and how many environments (test, staging, production) must be aligned. Change approval windows and the time needed to confirm the real addresses of each host also affect the schedule. Ask any provider for a written timeline tied to a defined scope rather than a generic estimate.
Can our internal team configure the allow list without outside help?
Usually yes, if your team has administrative access to the Collabora Online server configuration, the Nextcloud Office settings and your firewall or reverse proxy. The configuration keys are documented by Collabora and the Nextcloud side is a short settings change. The harder part is verification: confirming that every legitimate host is accepted, that unknown hosts are refused, and that the result survives upgrades and new integrations. Teams without an existing test habit for WOPI traffic often find this step takes the longest. Check your engineers' familiarity with WOPI, your reverse proxy and your change process before deciding.
What does the work need from our team before it starts?
Three inputs make the work predictable. First, a host inventory listing every storage system, collaboration platform or WOPI host that should open documents, with the exact domain names and the protocol each uses. Second, network diagrams showing where Collabora Online, the reverse proxy and each host sit, and which addresses reach which service. Third, a change window agreed with the owners of production services, plus a named contact who can approve firewall and proxy changes. Your team should also confirm which Collabora Online version you run, since configuration keys and behavior can differ between branches.
Can DeployOpen run the allow list setup and tests under a fixed-scope agreement?
DeployOpen works mainly under fixed-scope agreements, so the host list, environments, network changes and test cases are written down with deliverables and timelines before work starts. For this topic, the scope would normally cover reviewing the host inventory, configuring the Collabora Online allow list and matching Nextcloud settings, adjusting network restrictions where your team approves them, and testing that legitimate hosts are accepted and unknown hosts are refused, with the results documented. DeployOpen does not issue audit reports or certifications. Ask for the written scope and the list of responsibilities on both sides before signing.
What should we confirm with Collabora for our version before configuring the allow list?
Confirm the exact Collabora Online release you run, the configuration keys that release supports for WOPI host settings and aliasgroups, and whether your deployment method (Linux packages, Docker or Kubernetes) changes where those settings live. Check the release notes for the branch you use, and confirm whether you receive security updates through a supported plan or run a development build. The Collabora Online release notes and the Collabora Online pricing page describe the release history and support options. Record the answers in your change ticket so the configuration can be reproduced after an upgrade.
Limits to confirm in your environment
The allow list depends on details that vary by Collabora Online version, Nextcloud version and deployment method. The items below are the points to confirm with the vendor documentation and your own test environment before you write the configuration, so the restriction you test is the one you run in production.
Exact keys and aliasgroup syntax
Confirm the configuration keys and aliasgroup syntax against the documentation for the Collabora Online branch you run, not from older examples. Settings for WOPI host allow lists have changed shape across releases, and a key that is silently ignored leaves the server accepting any storage host. Record the exact branch, such as the version you deploy, and keep a copy of the reference used for your configuration.
Nextcloud version support
Check that your Nextcloud server and Nextcloud Office app versions support the WOPI settings you plan to use and the protocol matching you need. The Nextcloud administration manual covers restricting WOPI requests to Collabora server addresses, but the exact options and their behavior should be confirmed for your release. Plan the Nextcloud upgrade path alongside this check, because an upgrade can change how the editor connects.
How the deployment passes configuration
Confirm how your chosen method delivers the configuration: a packaged coolwsd.xml file, environment variables in a Docker container, or Helm values on Kubernetes. Each path has its own way of overriding defaults, and a setting written to the wrong file or variable will not take effect. After every change, check the running configuration rather than the file you edited, and confirm the restart or rollout picked it up.
Integration hosts listed by Collabora
Check whether each storage host you need to allow appears in Collabora's integration documentation or matches the host names your platform uses. Hosts listed on the product page, such as Nextcloud, ownCloud and Seafile, are a starting point only. Any other storage host needs its WOPI behavior confirmed with its vendor before you add it, because an unsupported host may fail in ways the allow list will not reveal.
Multi-server and COOL Controller behavior
Confirm how the allow list applies when several Collabora servers sit behind a load balancer or when the COOL Controller manages pods. Each server needs the same allowed hosts, and the load balancer must route all sessions for one document to the same instance. Test a request through every entry point, because a server missing the setting will accept hosts that others refuse.
What DeployOpen needs from you to scope this work
Scoping an allow list starts with an inventory of every WOPI host that will call your Collabora Online server. For a Nextcloud deployment that is usually the Nextcloud base URL and any other storage platform that will open documents in the editor. Give us the exact hostnames and schemes, the network path each host uses to reach the Collabora server (direct, through a reverse proxy, or through a NAT address), and the IP addresses or egress ranges those hosts present. Also send the Collabora Online version you run and whether it came from Docker, system packages or Kubernetes, because the way aliasgroup and wopi host settings are written depends on how the server was installed. Confirm the exact Nextcloud Office app version and Nextcloud server version too, since the app side of the allow list and the group restrictions in Nextcloud Office are configured there.
Send the network layout as a diagram or short written description: which reverse proxy or load balancer sits in front of the Collabora server, whether it passes the original Host header, whether TLS terminates there, and whether any ingress rules rewrite the WOPISrc parameter. We also need the access model you intend to apply in Nextcloud Office, meaning which groups may open documents in the editor and which may edit rather than only view. Name the owner of each decision, because the allow list has to match what the storage side actually sends, and a mismatch is the most common reason legitimate users see refused sessions. Tell us where your change tickets and approvals are recorded so the change record can match your process.
Under a written, fixed scope, DeployOpen delivers the allow list configuration for the Collabora server and the matching settings on the Nextcloud side, with each change documented against the host it affects. The test evidence covers requests from approved hosts that must succeed and requests from unknown hosts that must be refused, recorded with timestamps and the settings in force. The change record lists the files and settings changed, the values before and after, the person who approved each change, and the rollback steps. Scope, deliverables and timelines are agreed before work starts, and the quote follows from that written scope. DeployOpen does not issue audit reports, attestations or certifications. If you need evidence for an assessment, the independent auditor or certification body decides what it must contain, and we can prepare the configuration and test records they will ask to see.
How DeployOpen scopes, delivers and supports WOPI allow list work
DeployOpen treats the WOPI host allow list as a written scope item: which storage hosts and aliases Collabora Online must accept, how the Nextcloud side is matched, and how refusal of unknown hosts is proven before go-live. Engagements are fixed-scope, with the deliverables agreed in writing before work starts.
How we scope
- Inventory every WOPI host, alias and storage URL that must reach the Collabora Online server.
- Confirm the protocol and hostname used by Nextcloud so the Collabora server URL matches it.
- Agree in writing which test cases prove unknown hosts are refused before go-live.
How we build
- Configure aliasgroups and WOPI host settings on the Collabora Online server in your environment.
- Align the matching allow list in Nextcloud Office, including group limits on who may use the editor.
- Test refusal of unlisted hosts from a host outside the allow list and record the results.
How we hand over
- Deliver a configuration record listing each permitted host, alias and the owner who approved it.
- Document the change procedure for adding a new storage host, including the retest steps.
- Walk your operations team through the refusal tests so they can rerun them after upgrades.
How we support
- Review the allow list when storage hosts are added, renamed or retired.
- Check allow list settings again after each Collabora Online minor release you apply.
- Offer ongoing support and upgrades as a retainer, scoped in writing separately from the build.
