TLS and SSL termination for Collabora Online: where encryption should stop
TLS must be in place for any production Collabora Online deployment, so the real decision is where termination happens: on the Collabora Online server itself (coolwsd) or at a reverse proxy in front of it. Either model can be correct. What matters is that every hop carrying document content, WOPI calls and WebSocket traffic is encrypted, and that the choice is made deliberately and documented before the first user opens a file. This page covers the termination choices, certificate handling, cipher and protocol settings, and how to keep them aligned with the WOPI host. The Nextcloud administration manual gives a clear starting rule: the Collabora server URL should use the same protocol as the Nextcloud installation, preferably HTTPS. Mixed schemes are a common source of mixed-content and connection failures, so check the protocol on both sides before testing. Read the relevant Nextcloud section on Nextcloud Office configuration when you record the decision. If the WOPI host is not Nextcloud, confirm the same requirement with that platform's documentation rather than assuming it.
For most organizations, terminating TLS at a reverse proxy is the simpler model. The proxy holds the certificate chain, applies a single cipher and protocol policy, handles renewal, and forwards traffic to coolwsd over a connection you control. Terminating on coolwsd keeps encryption end to end on a single process, which can suit restricted networks, but it moves certificate handling and cipher maintenance onto the Collabora host. Whichever you choose, confirm that WebSocket upgrades pass through the proxy intact, that the proxy forwards the original host and protocol headers, and that the certificate covers the exact hostname the WOPI host will call. Test the result from the WOPI host's network, not only from your workstation. Verify the certificate chain is complete, that legacy protocol versions are refused, and that the cipher list matches your policy. Ask your team or partner to confirm the exact settings in your environment, since the parameters depend on your proxy and Collabora version. Record the renewal owner and the expiry alert, because an expired certificate stops editing for every user at once.
Choosing TLS on coolwsd or termination at a reverse proxy
Collabora Online can serve HTTPS itself through coolwsd, or leave TLS to a reverse proxy in front of it. The choice shapes certificate handling, WebSocket behavior, and who on your team maintains the configuration. The cards below cover the decisions that connect these two patterns.
TLS handled directly by coolwsd
With coolwsd terminating TLS, the Collabora Online server itself holds the certificate and private key and accepts HTTPS connections. This keeps the path short and avoids a separate proxy layer, but certificate renewal, key file permissions and restarts after rotation become tasks for the server team. Check how your deployment method (package, Docker or Kubernetes) mounts certificate files, and confirm the exact configuration keys for your version in the current docs.
SSL termination at a reverse proxy
With termination at a reverse proxy, Nginx, HAProxy or another front end holds the public certificate, handles the TLS handshake and forwards plain traffic to the Collabora Online service on a private network. Certificate lifecycle usually sits with the team that already runs the proxy. Decide whether traffic between the proxy and coolwsd stays on a trusted segment, because that hop is then unencrypted unless you add a second layer of TLS.
Supported ingress in the Helm chart
The official Helm chart README lists Nginx, HAProxy and the OpenShift Router as supported ingress options, which points Kubernetes deployments toward termination at the ingress layer. Confirm how the chart exposes TLS settings and certificate secrets for your chart version, and whether the ingress must also route by the WOPISrc parameter so all users editing one document reach the same pod.
WebSocket pass-through
Collabora Online editing depends on persistent WebSocket connections, so the proxy must upgrade and hold those connections, not only forward ordinary HTTP requests. Misconfigured upgrade headers or short idle timeouts show up as dropped sessions during editing rather than as clear TLS errors. Test a long editing session through the exact proxy configuration you plan to run, and confirm the required directives in the docs for your proxy and version.
Matching protocols with the WOPI host
The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. Whichever pattern you choose, the scheme the WOPI host sees and the scheme the browser sees must agree, or redirects and mixed-content blocks break document opening. Verify both sides with a test document after every certificate or proxy change.
Operator skills and ownership
Choose the pattern your team can operate under pressure. Coolwsd termination suits a team comfortable editing server configuration and rotating certificates on the Collabora hosts. Proxy termination suits teams that already run Nginx, HAProxy or an OpenShift Router with automated certificate issuance. Write down who owns certificate renewal, cipher list updates and proxy upgrades before go-live, and confirm that the same people can respond to a failed renewal.
Which TLS configuration fits which deployment
This table compares four TLS layouts for Collabora Online: TLS on coolwsd itself, reverse proxy termination with plain HTTP behind it, end-to-end TLS to the backend, and a Kubernetes ingress with a managed certificate. Read each row for the setup that fits your topology, what you maintain, and the trade-off you accept. Confirm every choice against the Collabora and Nextcloud documentation for your release.
| Layout | When it fits | What the operator maintains | Main trade-off |
|---|---|---|---|
| Single server with coolwsd TLS | One host with no reverse proxy, where coolwsd terminates HTTPS directly | Certificate files, private key permissions, renewal and the coolwsd SSL settings | Fewer moving parts, but certificate handling sits in the Collabora service itself |
| Reverse proxy termination with internal HTTP | A proxy such as Nginx, HAProxy or Apache already fronts your services on a trusted internal network | Proxy certificates and cipher policy, proxy headers, and the WOPI host protocol match | Simple to operate, but traffic between proxy and Collabora is unencrypted |
| End-to-end TLS to the backend | Policy requires encryption on internal network segments or hosts are not fully trusted | Certificates on both the proxy and coolwsd, trust chains, and renewal on both sides | More certificates to rotate and more places where a handshake can fail |
| Kubernetes ingress with managed certificate | Collabora runs in a cluster and the ingress controller issues or attaches certificates | Ingress and certificate manager configuration, issuer access, and the cluster TLS policy | Automated renewal, but behavior depends on the ingress controller and cluster add-ons you confirm |
Setting up HTTPS for Collabora Online step by step
This sequence takes Collabora Online from a plain HTTP test install to an HTTPS endpoint that Nextcloud and other WOPI hosts can reach with a matching protocol, with a check at each step so you know it is working before you move on.
Confirm the public hostname and DNS record
Decide the fully qualified domain name that users and the WOPI host will use to reach Collabora Online, such as the name you publish for the editing service, and create the DNS record that points it to the proxy or server. Confirm the name resolves from the Nextcloud network and from user networks, and that it is the same name the certificate will cover. Check this with a DNS lookup from both sides. If the name resolves differently inside and outside your network, record both answers now so the certificate and the WOPI host settings match each one.
Obtain and install the certificate chain
Request a certificate for the confirmed hostname from your internal certificate authority or public CA, following your organization's key length and validity policy. Install the leaf certificate and its intermediate chain in the location you chose, either on the reverse proxy or in the coolwsd configuration, and restrict the private key file so only the service account can read it. Confirm the chain with an OpenSSL client check against the hostname, looking for a complete chain and a matching subject name. A missing intermediate is the most common cause of later browser and WOPI host errors, so do not skip this check.
Configure the proxy or coolwsd listener
Choose one termination point. For SSL termination at a reverse proxy, configure the proxy to listen on port 443, present the certificate, and forward WebSocket upgrade requests to Collabora Online over HTTP on the internal network. For TLS on coolwsd, set the SSL options in the coolwsd configuration so the server terminates TLS itself. Validate the configuration file syntax with the proxy or coolwsd tool before reloading the service. Then confirm that the listener is open on the expected port with a socket check, and that a request to the hostname returns the Collabora Online landing response over HTTPS without a certificate error in a command-line client.
Set the server URL to match Nextcloud
Set the Collabora Online server URL in the WOPI host configuration so it uses the same protocol as the Nextcloud installation. The Nextcloud administration manual recommends using HTTPS for the Collabora server URL where Nextcloud itself uses HTTPS. Enter the public hostname, not an internal address, and confirm the URL in the Nextcloud Office settings. Check it by reading the saved value back in the admin interface and by confirming Nextcloud can open the discovery document from the server using the same scheme. A scheme mismatch here produces errors that look like connection failures, so verify the scheme explicitly.
Restrict protocols and cipher suites to policy
Set the minimum TLS protocol version and the cipher list in the proxy or coolwsd configuration to match your organization's written policy. Remove legacy protocol versions and weak cipher suites, and confirm that the chosen set still supports the clients and WOPI hosts you expect. Test with a TLS scanner or an OpenSSL client run for each protocol version you intend to refuse, and confirm the handshake fails. Record the accepted protocols and suites in your change record. If a client fails after tightening, check its supported protocol version before loosening the policy.
Run a browser test on a document
From a user workstation on the expected network, open the Collabora Online editing service through Nextcloud, not only the bare hostname, and open a sample document in Writer or Calc. Confirm the padlock shows a trusted certificate for the hostname, the document loads without a mixed content warning, and edits save back to the file store. Repeat the test from a second browser to catch certificate chain differences. Keep the sample document free of sensitive content. A document that opens and saves over HTTPS is the functional proof that the whole path works end to end.
Verify the WOPI discovery endpoint
Request the WOPI discovery document from the Collabora Online hostname over HTTPS, using a command-line client from the Nextcloud server. Confirm the response is valid, that the URLs it lists use the https scheme and the public hostname, and that the response is served with the expected certificate. Repeat the request from a host outside the allowed WOPI source range to confirm that the restrictions you set elsewhere still hold. Record the discovery output with the date and the configuration version so you can compare it after future upgrades or certificate renewals.
Why protocols must match between the WOPI host and Collabora
The protocol in the Collabora server URL must match the protocol the WOPI host uses, and in production that should be HTTPS on both sides. The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. When one side is HTTP and the other is HTTPS, the failure often shows up as an editor that never loads, a discovery request that the host rejects, or a WOPI callback that goes to an address the browser or the server cannot reach securely. These errors look like network faults, so teams lose time on firewalls before they check the URL scheme. Write down the scheme for the WOPI host, the Collabora discovery URL and any external address the proxy advertises, then confirm all three agree before you test editing.
Mixed content is the second trap. A browser that loads the Nextcloud page over HTTPS will block an editor frame or script fetched over plain HTTP, and modern browsers generally refuse to open insecure WebSocket connections from a secure page. Collabora's editing traffic runs over WebSocket, so the wss:// path has to be terminated with a valid certificate just like the page itself. A proxy that handles HTTPS for the page but forwards the WebSocket upgrade without the right headers can produce a session that appears to open and then drops during the first edit. Test the upgrade path explicitly from a browser on the user network, not only with a command-line request.
Protocol behavior depends on the versions in your stack, so confirm it before you standardize on a configuration. Check the current Nextcloud Office configuration guidance for the WOPI host version you run, and check Collabora's documentation for the server version you deploy, since handling of mixed schemes and WebSocket forwarding has changed between releases. Record the results in your change record so the next upgrade of either side starts from a known-good state.
Certificates, ciphers and protocol hardening decisions
Once TLS terminates at a reverse proxy, the proxy becomes the main control point for certificates, protocol versions and cipher choices. The cards below cover the decisions that connect the certificate chain, key handling, renewal and transport policy, and the testing needed before any setting changes.
Complete the certificate chain
Serve the leaf certificate together with every intermediate certificate the issuing authority requires, so browsers and the WOPI host can build a trusted path without guessing. A chain that works in one browser but fails in a server-side client is a common cause of intermittent WOPI errors. Check the chain from outside the proxy network with a command-line TLS client, and confirm that the names on the certificate cover the Collabora Online hostname that Nextcloud or another WOPI host uses.
Store and restrict private keys
Keep the private key readable only by the proxy process and the account that manages certificates, and never place it in a container image, a shared configuration repository or a ticket attachment. Where your policy requires it, hold keys in a hardware security module or a managed secrets store and record who can export them. Ask your proxy vendor or team which file permissions and key formats they expect, and test reload behavior after rotating the key.
Automate certificate renewal
Renewal should run unattended, reload the proxy without dropping active editing sessions, and alert someone when it fails. Track the expiry date of each certificate on the Collabora hostname and the Nextcloud hostname, since a lapse on either breaks document opening. Confirm the renewal method with your certificate authority and test a failed renewal so that the alert path is proven before the first real expiry.
Disable legacy protocol versions
Allow only the TLS versions your security policy names, and remove older SSL and TLS versions from the proxy configuration. Before you remove one, confirm with the Nextcloud and Collabora administrators which protocol versions the WOPI host connection uses. The Nextcloud administration manual recommends matching the protocol used for the Collabora server URL with the one used for the Nextcloud installation, so align both sides before tightening the proxy.
Choose cipher lists against policy
Select the cipher suites from the cryptographic baseline your organization already applies, rather than copying a list from an older guide. Remove suites your policy prohibits, and keep forward secrecy enabled. Record the chosen list in version control so that changes go through review. Expect some clients or older Java or PHP runtimes to fail after tightening, and confirm the impact against a test environment before production.
Set HSTS with care
HTTP Strict Transport Security tells browsers to use HTTPS only for the host. Set a moderate maximum age first, then increase it once you have confirmed that every hostname under that domain serves valid HTTPS. Adding subdomain coverage affects every service on that domain, so review it with the teams who run the other services. Note that HSTS governs browser behavior and does not protect the server-to-server WOPI connection.
Restrict admin endpoints at the proxy
Block external access to the admin console and its WebSocket endpoint at the reverse proxy, allowing only the administration network or a jump host. The admin path should not be reachable from the same address space as end users. Protecting the admin console covers credentials and logging in more depth, so use this card to confirm that the proxy rules deny the path before any application-level login is tested.
Test with the actual clients
Every tightening change can break a client that your users or your WOPI host depend on, so test each change against the real Nextcloud server, the browsers your staff use, and any command-line or server-side clients. Keep a record of the handshake results before and after the change, and roll back if document opening fails. Ask your team to list the clients they support so the test matrix is complete before the change window.
TLS questions buyers ask before hiring help
Is HTTP ever acceptable for Collabora Online in production?
No. Plain HTTP should not be used in production for Collabora Online. Document content, session tokens and WOPI access tokens travel between the browser, the Collabora server and the storage host, so anyone on the path could read or alter them. The Nextcloud administration manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. HTTP may appear briefly during a lab test on a closed network, but the production design should assume HTTPS from the first day, with the certificate chain and browser behavior tested before users arrive.
Should TLS run on coolwsd or at the reverse proxy?
For most organizations, terminating TLS at a reverse proxy is the more common and easier-to-operate choice, because the proxy already handles certificates, cipher policy and renewal for other services. The proxy must still forward WebSocket upgrades correctly, and the WOPI host must reach the Collabora URL over the same scheme it was configured with. Terminating TLS on coolwsd itself keeps the chain short but puts certificate handling inside the Collabora service. Whichever you choose, the decision should be written down, tested end to end, and matched in the WOPI host settings.
What drives the cost of a TLS setup project?
Cost follows the work that someone must do and the people who must be paid to do it. The main drivers are the number of Collabora servers and proxies, how certificates are issued and renewed, the skills your proxy team already has, how many client platforms and browsers must be tested, and whether the WOPI hosts sit on separate networks. Setup is usually one-time work, while certificate renewal, cipher review and patching of the proxy recur. Ask any partner for a quote built from a written scope that lists each server, hostname, certificate source and test matrix, since the quote follows that scope.
What certificate sources should we plan for?
The usual sources are a public certificate authority, an internal certificate authority that your clients already trust, or a certificate issued by a platform tool your organization already runs. Each one has different owners, approval steps and renewal processes, and each affects how long the first rollout takes. Confirm with your security team who can request certificates, how renewal is automated, whether the WOPI host and browsers trust the issuing chain, and whether the certificates need to cover internal names that are not published in public DNS.
How long does TLS setup usually take?
The duration depends on the environment rather than on a fixed figure. Teams with an existing reverse proxy, a certificate process and a test plan can move quickly, while new certificate authorities, multiple data centers or strict change windows add time. Ask for a timeline that is tied to the written scope, and make sure it names the approval steps, the test environment and the production change window. Confirm these inputs with your own change board before agreeing to any date.
What does our team need to provide before work starts?
A partner will need a clear picture of your environment. Typically this includes the public and internal hostnames for the Collabora server and the WOPI hosts, access to or a process with the certificate authority, the current proxy configuration and its owner, and a network diagram showing which systems can reach which ports. You should also provide a list of client browsers and operating systems that must work, plus access to a test environment that mirrors production. Missing inputs usually become the largest source of delay.
Can our own team set up TLS for Collabora Online?
Often yes, if your team already runs a reverse proxy and manages certificates. The work is mostly configuration: certificate files, cipher and protocol settings, WebSocket forwarding and matching the WOPI host URL. The harder part is testing across clients and confirming that the Collabora configuration and the WOPI host agree on protocol. If your team lacks proxy or WebSocket experience, a fixed-scope engagement can cover the build and hand over the runbook, while your staff keep ownership of renewals and changes.
What should we verify after TLS is in place?
Verify the chain from the browser, the WOPI host and the Collabora server, not only the proxy. Check that the certificate covers every hostname used, that the chain is complete, that the WOPI host accepts the Collabora URL, and that editing works in each supported browser. Confirm that WebSocket connections upgrade over the secure scheme and that certificate expiry is monitored. Keep the test results with your change record, since auditors and security reviewers usually ask for them.
How DeployOpen scopes TLS work for Collabora Online
DeployOpen scopes TLS work for Collabora Online as a fixed-scope engagement that starts with a written decision on where encryption terminates: directly on coolwsd, or at a reverse proxy in front of it. The scope document records the chosen design, the hostnames and certificate chain for the Collabora Online URL, the WOPI host (for example Nextcloud) and any load balancer in between, the TLS protocol versions and cipher lists agreed with the client's security team, and the protocol the WOPI host will use to reach the server. Because the Nextcloud administration manual recommends using the same protocol, preferably HTTPS, for the Collabora server URL as for the Nextcloud installation, the scope also names the expected protocol on each side of the hand-off. The deliverables are the configuration files and change records for the agreed environment, a test plan, and an operations note explaining how certificates are renewed. The client's own infrastructure remains the place where everything runs, and DeployOpen works through the access the client grants for that environment.
Verification is written into the scope so the client knows what evidence arrives at handover. Typical checks include confirming that no WOPI or editing traffic is served over plain HTTP in the production path, that the certificate chain validates from the WOPI host's network segment, that the WOPI host reaches the Collabora URL with the expected protocol, and that a document opens and saves end to end. DeployOpen prepares these configurations and this evidence so the client's own assessors can review them, but DeployOpen does not issue audit reports, attestations or certifications. Independent auditors and certification bodies make those determinations. Clients who need assessment-ready records should confirm with their assessor which artifacts they expect, such as scan output, configuration exports and change history, and agree on those artifacts before work begins. After handover, certificate renewal, protocol changes after a Collabora Online upgrade, and changes to the WOPI host's own TLS settings can all break editing. DeployOpen offers optional retainer support for monitoring these items, re-running the verification plan after changes, and reviewing new Collabora Online releases before they reach production. Retainer terms, response expectations and the list of covered environments are agreed in writing and priced separately from the fixed-scope work. Clients should ask for the verification checklist, the list of artifacts delivered, and the retainer terms in any quote.
