How WOPI proof keys verify Collabora Online requests
If you run a custom WOPI host, you need a way to confirm that a file request really came from your Collabora Online server and not from someone who has guessed or copied a WOPI URL. WOPI proof keys are the mechanism for that check. Collabora Online signs the X-WOPI-Proof header on requests it sends back to the host, and the host verifies that signature against public keys that Collabora publishes in its discovery document. A request that fails verification should be refused, so the host only serves file content to the editing server it trusts. Without this check, the access token and the WOPISrc parameter are the only gatekeepers, and a leaked token is enough to read or write a document.
Teams usually need proof keys when they build their own WOPI host rather than relying on a mature integration, when the storage service is reachable from shared or public networks, or when security policy requires every inbound request to be cryptographically verified. The Nextcloud side is covered by different controls: the Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers and using HTTPS for the Collabora server URL. Those measures complement proof keys but do not replace them, because IP restrictions can be bypassed in some network designs and proof keys bind verification to key material your host can check directly.
Treat the exact key generation steps, the coolconfig options and the discovery field names as items to confirm against Collabora's current documentation for the version you deploy, since these details can change between branches. Before you build verification, confirm how keys are generated and rotated, which discovery fields carry them, and how the signed string is constructed, then test with a request that has a missing or altered signature and check that your host rejects it. Plan key rotation so that sessions already open continue to validate while new keys are introduced.
Choosing how much verification your WOPI host needs
This table compares three levels of checking that a WOPI host can apply to requests coming from Collabora Online, from an IP allow list alone to proof keys combined with access token checks and a rotation schedule. Read each row against your threat model and your own build capacity. The main takeaway is that an IP allow list is a network control, while proof key verification confirms that the request came from the Collabora server that holds the private key.
| Option | What it protects against | Build and operations effort | When it fits |
|---|---|---|---|
| IP allow list only | Requests from hosts outside the Collabora server addresses, which narrows who can reach your file endpoints | Low build effort in the WOPI host, but addresses must be kept current as servers move, scale or sit behind changing NAT or load balancers | Small, fixed deployments on a private network where Collabora addresses rarely change and the WOPI host is not exposed to untrusted callers |
| Proof key verification in the WOPI host | Forged WOPI calls that a caller makes without the Collabora private key, including calls from hosts that happen to be on an allowed network | Moderate build effort: parse the X-WOPI-Proof and timestamp headers, rebuild the signed input, and check the signature against the published public key | Shared or multi-tenant networks, or any setup where the WOPI endpoint is reachable beyond the Collabora servers |
| Proof keys with access token checks and a documented rotation schedule | Forged calls, replayed or stale requests, and token reuse across files or users, with a defined path for key changes | Highest effort: token issuance and validation, scoping per file and user, rotation runbook, and tests for overlapping old and new keys | Regulated or sensitive document workloads where assessors expect layered controls and evidence of key lifecycle management |
Setting up WOPI proof keys with coolconfig
This sequence generates a proof key pair on the Collabora Online server, exposes the public key through WOPI discovery, and configures a WOPI host to fetch, cache and check it. The end result is a host that accepts only requests whose X-WOPI-Proof headers verify against the server's key, and rejects unsigned or altered ones.
Confirm the server and WOPI host baseline
Before changing anything, the Collabora administrator and the WOPI host owner record the installed Collabora Online version, the host platform and the URL the host uses to reach the WOPI discovery endpoint. Proof keys depend on the server build and on how the host fetches discovery, so the version has to be known before the commands in the next steps are run. Confirm the exact command syntax and file locations for that version in Collabora's documentation, because they can differ between packages, Docker images and Kubernetes deployments. The check is a written record of version, host and discovery URL, reviewed by both teams.
Generate the proof key pair with coolconfig
On the Collabora server, the administrator runs the coolconfig utility shipped with the installation to generate a new proof key pair. The private key stays on the server and is used to sign the X-WOPI-Proof headers that Collabora sends to the host. Store the private key with restrictive file permissions and keep it out of version control and shared configuration templates. The check is that the key files exist in the location confirmed in the previous step, are readable only by the service account, and that the configuration references them without a parse error when the service restarts.
Publish the public key through discovery
After the restart, the administrator fetches the WOPI discovery document from the Collabora server and locates the proof key entries. The public key and its modulus and exponent values are what the WOPI host needs to verify signatures. Confirm which discovery fields carry the current key and whether an older key is also listed, since that affects rotation later. The check is that the discovery response contains the expected public key values and that they match the public half of the pair generated in the previous step.
Configure the WOPI host to fetch and cache the key
The WOPI host owner configures the host so it reads the public key from discovery and stores it in a cache with a defined refresh behavior. Caching avoids a discovery call on every file request, but a stale cache will reject signatures made with a newly rotated key, so the refresh interval and the failure behavior need to be decided and documented. In a custom host, this is usually a small component that parses the discovery response, builds the verification key and retries discovery when verification fails. The check is that a fresh start of the host loads the key from discovery and logs the key identifier it loaded.
Verify a signed test request
The team triggers a real WOPI request from the integration, such as a CheckFileInfo call for a test document, and captures the request and its X-WOPI-Proof and X-WOPI-ProofOld headers. The host reconstructs the string that was signed, using the access token and the request URL as defined by the WOPI specification, and verifies the signature with the cached public key. Keep the test file non-sensitive and use a test user. The check is that the host logs a successful verification for the request and that the verification uses the key identifier loaded in the previous step.
Confirm tampered and unsigned requests are rejected
The team sends the same request with the URL altered, with the access token changed, with the X-WOPI-Proof header removed, and with a signature copied from a different request. Each variant must be refused by the host with a clear error and logged as a verification failure, and the file operation must not proceed. Run these tests against the staging host before production, and record the results. The check is a written test result showing that every altered variant was rejected and that the valid request was accepted, with the outcomes kept as evidence for the security review.
Document the rotation procedure before go-live
Before the integration goes into use, the team writes down how the key pair will be rotated: how the new pair is generated with coolconfig, how the old key remains published during the overlap so that open sessions keep verifying, how the host refreshes its cache, and who approves the change. Rotation is covered in detail in the rotation section of this page. The check is a reviewed runbook stored with the deployment documentation, and a rehearsal of the discovery refresh on staging that shows the host picks up a new key without a restart.
Rotating WOPI proof keys without breaking open sessions
The core risk in rotating WOPI proof keys is timing. Documents stay open in browsers for hours or days, and a WOPI host may fetch discovery once and cache it. If the Collabora server starts signing X-WOPI-Proof headers with a new key before the host has the matching public key, requests for sessions already in progress will fail verification. The safe approach is an overlap window: publish the old and new public keys together in discovery, switch the signing key on the Collabora side, and only retire the old key after every host has picked up the change and no session that began under it remains open. Confirm with Collabora exactly which proof key fields discovery exposes during a transition, and whether the server can hold a second key for verification while signing with the first. Do not assume either behavior from this page.
Refresh is the step most often missed. Your WOPI host, any reverse proxy or cache in front of discovery, and your own key-fetching code each need a defined refresh interval, and that interval must be shorter than the overlap window. Make the refresh logic fail safe: if fetching discovery fails, keep the last good key set rather than dropping to a single key, and alert on the failure. Schedule rotation separately from Collabora patch windows where you can, because a minor release may also change configuration or restart the server, and you want one change at a time. Where a security advisory forces a key change during a patch cycle, follow the patching process described in the advisories guidance and expect a shorter overlap.
Test the full sequence in a staging environment that mirrors production discovery caching before touching production. Open a document, hold the session, rotate, and confirm that edits, saves and lock refreshes still succeed on both the old and new keys. Then deliberately break the refresh path and confirm the host behaves as your runbook says. Record how long each stage takes in your own environment, because no duration for these steps has been established for your deployment. Ask your Collabora support contact, or the vendor documentation for your branch, to confirm the key lifecycle before you write the runbook, and keep the staging results as evidence for your change record.
Security checks a custom WOPI host should run on every request
Proof key verification only protects you if every check around it holds. The cards below cover the signature, the timing rules, key freshness, key custody, logging and the network controls that sit alongside proof checks. Each one fails in a different way, so each needs its own test.
Validate the signature over token and URL
Rebuild the exact string the WOPI host expects from the access token and the full request URL, then verify the X-WOPI-Proof signature against the matching public key. The most common failure is a URL mismatch caused by a reverse proxy rewriting the host, scheme or path before your code sees it. Check the URL as the client originally requested it, and test with a request that has a single character changed to confirm rejection. Treat any mismatch as a failed verification, not a warning.
Enforce the timestamp window
Read the timestamp header sent with each request and reject requests outside a short acceptance window. The window must be wide enough to absorb normal clock drift between the Collabora host and your WOPI host, but narrow enough that a captured request cannot be replayed later. Confirm the acceptable skew with your own team, then test it by sending requests stamped slightly in the past and future. Keep both servers on synchronized time sources, because a drifting clock causes intermittent failures that look like random auth errors.
Refresh discovery without trusting old keys
Your WOPI host should fetch the discovery document that publishes the proof keys, cache them, and refresh them on a schedule. Caching is necessary for performance, but a cache with no expiry will keep accepting a retired key indefinitely after rotation. Set a maximum cache age, and when a signature fails against a cached key, fetch discovery again once before rejecting. This lets open sessions survive a rotation while stopping revoked keys from remaining valid.
Protect the private key on the Collabora host
The private key that signs proof headers is the trust anchor for the whole integration. Store it with restricted file permissions, limit read access to the coolwsd service account, and keep it out of container images, configuration repositories and shared backups. Ask who can read the key on your side and on the Collabora side, and record the answer. A leaked private key lets an attacker forge requests that your host will accept until the key is replaced.
Log every failed verification
Record each failed proof check with the file identifier, the requesting user where known, the source address, the key identifier used and the reason for failure. Failures cluster around rotation windows, clock problems and misconfigured proxies, so the log is how you tell an attack from an outage. Alert when failures spike for one source or one file, and keep the entries long enough for your incident process. Do not log the full access token, since that would turn your log store into a credential store.
Combine proof checks with IP restriction
The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers. Proof checks and network restriction catch different failures: an IP allow list stops traffic from unexpected hosts, while proof verification confirms that a request was signed by the holder of the key. Use both where your network allows it, and document the Collabora server addresses so the list is updated when servers change. Test that a request from an address outside the list is refused even when it carries a valid-looking signature.
What to confirm before you rely on proof keys
Nextcloud is the most common WOPI host, and its integration handles much of the WOPI plumbing for you. Before you depend on proof keys in this setup, confirm how your installed Nextcloud Office app and your Collabora Online version expose and consume the keys, because the handoff between the two is where teams most often assume too much. Start with the Nextcloud administration manual for the Nextcloud Office configuration, then check the release notes for your exact Collabora branch.
- Coolconfig invocation: Confirm the exact
coolconfigcommand and arguments your installed version accepts for generating proof keys, and where it writes the output. - Discovery field: Confirm which field in the WOPI discovery document carries the public key and whether Nextcloud reads it from there or from a configuration value.
- Supported key formats: Confirm which key encodings your version emits and whether the Nextcloud side accepts them without conversion.
- Rotation behavior: Confirm whether Nextcloud caches the old key, how long it keeps accepting it, and whether open sessions survive a rotation.
- Test path: Confirm that a deliberately wrong proof key produces a refused request on your instance, not just a log warning.
Check each of these against the version you run, not against the latest documentation.
A custom WOPI host has no vendor integration layer, so your team owns the entire verification path: fetching discovery, selecting the right key, computing the expected signature over the request, and rejecting mismatches. The gaps are usually in details the protocol documentation leaves to the implementer, such as timestamp handling and which key applies after a rotation. Confirm each of these with the Collabora documentation for your version and with your own tests before you write enforcement code.
- Discovery parsing: Confirm the discovery field name and structure your version publishes, and whether the key is a single value or a set.
- Key format and algorithm: Confirm the key encoding, the signature algorithm and the exact string that is signed, including the request URL and timestamp format.
- Clock and timestamp rules: Confirm the timestamp unit and any tolerance window your version expects, and how your host handles clock skew.
- Rotation handling: Confirm whether discovery returns the old and new keys during overlap, and how long your host should keep the previous key for in-flight sessions.
- Failure behavior: Confirm what Collabora does when verification fails and what your host should return, so you do not break editing for legitimate users.
Run the verification against captured requests from a real Collabora server before you enforce it.
In Kubernetes or Docker deployments, the question is less about the protocol and more about where the key material lives and how it survives restarts, image updates and replica changes. The official Helm chart README and the Docker image documentation describe their own storage and configuration mechanisms, and those can differ between chart versions and image tags. Confirm the storage path and the generation step for your chart and image before you assume keys persist across pods.
- Key storage: Confirm whether the Helm chart or Docker image stores proof keys in a generated file, a Kubernetes Secret, a mounted volume or an environment value, and whether the chart can reference an existing Secret.
- Generation step: Confirm whether keys are generated at container start, by an init step, or manually with
coolconfig, and whether each replica would generate its own key. - Replica consistency: Confirm that all pods serving a document use the same key set, since the chart README requires WOPISrc-aware routing for documents, and key drift would break verification on some requests.
- Rotation procedure: Confirm how a rolling restart interacts with key rotation and whether the chart supports overlapping keys.
- Backup and recovery: Confirm that the key material is included in your secret backup and that restoring it does not invalidate open sessions.
Verify the chart and image tags you deploy, because storage behavior is version specific.
Questions teams ask before building proof key checks
How much effort does proof key verification take to build?
Proof key verification is a small code change in the WOPI host, but the effort around it is what varies. The main drivers are how many WOPI host code paths make file requests, whether your host already has a shared library for WOPI calls, how cleanly you can read the raw request URL and headers before any framework normalizes them, and how many environments need separate key handling. Cost comes from engineering time for the verifier, the tests that prove it rejects bad signatures and stale timestamps, and the staging work to rotate keys without an outage. Ask any partner for a fixed-scope quote that lists each WOPI endpoint covered, the test cases, and the staging environment used for the rotation test.
How long does a proof key build usually take?
The duration depends on the shape of your WOPI host, not on the verification algorithm itself. Teams with one well-structured file service usually have a shorter path than teams that proxy WOPI calls through several services, store file metadata in multiple places, or run several Collabora Online servers with different keys. Other factors include how quickly you can get a staging Collabora server that matches production, how many reviewers must sign off on security code, and whether rotation has to be rehearsed before go-live. Confirm the timeline in writing with your partner or internal owner, and ask which steps depend on your own change approvals.
Can our in-house team build proof key checks without a partner?
Yes, a team with experience in signature verification, HTTP request handling and secure key storage can build this internally. The work is well defined, and the Collabora Online documentation describes the headers and discovery values involved. The risks lie in edge cases: clock skew handling, reading the exact request URL behind a reverse proxy, caching the public key correctly, and testing rotation with open sessions. Most teams find that the test suite and the rotation rehearsal take more effort than the verifier. If your team lacks that experience, an outside review of the design and tests is a common middle path.
What do we need to provide for a proof key engagement?
You will need read and write access to the WOPI host code that handles CheckFileInfo and file content requests, along with the configuration for how requests reach it. A staging Collabora Online server that you control is needed to test signed requests end to end, and it should run a version close to production. You also need a named rotation owner who can schedule key changes, approve the rollout, and respond when sessions fail. Provide your current allow list and reverse proxy configuration so the verifier is tested behind the same path real traffic takes. Agree on who holds the private key material and where it is stored before work begins.
Do proof keys replace IP allow lists?
No, proof keys complement IP allow lists and do not replace them. An IP allow list limits which network sources can reach your WOPI endpoints, which the Nextcloud administration manual recommends for restricting WOPI requests to the Collabora server addresses. Proof key verification checks that a request was signed with the key that your Collabora server published in discovery, which protects your host even if network controls change or a request arrives through a path you did not expect. Keep both controls. Test each one separately, because a failure in one should not silently disable the other.
How do proof key checks fit into patching and upgrades?
Proof key work should be planned as part of every Collabora Online upgrade, not as a one-time project. When you apply a minor release, check whether discovery values, key formats or header handling changed in the release notes, and confirm that verification still passes in staging before production. Package signing key changes, such as those recorded in the 25.04 release notes, are a separate patching concern that affects how you install updates, so track both. Schedule key rotation on its own cycle, and do not combine it with a security patch unless you have tested the combined change. Ask your partner for a written upgrade checklist that includes the proof key tests.
How DeployOpen scopes WOPI proof key work
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Collabora Online. For WOPI proof key verification, we start from your WOPI host, your Collabora Online deployment and your rotation requirements, then agree the work in writing before any change is made.
How we scope
- Inventory every WOPI host and Collabora Online server that must verify proof key headers, with their current discovery endpoints.
- Agree in writing which proof key generation, publication, verification and rotation tasks are in the fixed scope.
- Record the rotation policy, outage tolerance for open sessions and who approves key changes before the build starts.
- Confirm with your team the exact WOPI host stack and language, since verification code depends on it and cannot be reused blindly.
How we build
- Generate proof keys with coolconfig on a controlled host and store the private material in your existing secrets system.
- Publish the public keys through discovery, then test header verification against a staging WOPI host before production use.
- Implement X-WOPI-Proof verification in your custom WOPI host, with tests for valid, expired, tampered and missing headers.
- Build the rotation procedure so the old and new keys overlap long enough for open editing sessions to finish safely.
How we hand over
- Deliver the configuration, verification code, test cases and rotation runbook in your repositories, under your ownership.
- Document each step, the key locations, the discovery checks and the rollback path so your engineers can repeat the process.
- Run a walkthrough with your platform and security teams so they can perform a rotation without DeployOpen present.
- Provide a checklist for confirming with Collabora's documentation and your release notes that the version in use still behaves as described.
How we support
- Engagements are fixed-scope, and any change to the agreed scope is documented and priced in writing before work continues.
- Ongoing support, upgrades and continuous testing for proof key handling are available as a retainer.
- Retainer scope can cover re-testing after Collabora Online upgrades, rotation support and review of new WOPI host releases.
