Why access token design decides who can edit a document in Collabora Online
If you run a WOPI host such as Nextcloud, you decide how access tokens are issued when your host answers CheckFileInfo, and that decision determines who can open a document in Collabora Online and with what rights. A WOPI access token is the credential Collabora Online presents back to your host on each request for a file. It authorizes a specific user to read or edit a specific file for a limited period, so the token design, not the link a user clicks, is the main control between a shared link and a live editing session. Access token design for Collabora Online integrations therefore belongs to the integration owner, not only to the people who installed the server.
Teams should design token handling themselves when their access model is more detailed than the host default. Nextcloud's own administration controls, such as limiting which groups can use the editor and which groups can edit rather than only view, are a starting point, but they only hold if every token the host issues carries the same user, file and permission decisions. Your team should confirm, for the host version you run, how long tokens live, whether a token is bound to one file and one user, what happens to an open session when a share is revoked, and whether the host accepts tokens in the Bearer header as well as in the query string. Those answers belong in your written design before rollout, not after an incident.
Scope the design as a set of checks you can test. Issue tokens only after the host has confirmed the requesting user's rights to that file at that moment, keep lifetimes short enough that a revoked permission ends editing quickly, and reject any token presented against a different file identifier than the one it was issued for. The exact mechanics depend on your host and Collabora Online version, so confirm them against the Nextcloud Office configuration documentation and your own tests rather than assuming a default is safe.
Token options and when each design fits
This table compares the main WOPI access token design choices for Collabora Online integrations, including lifetime, scope, session model and how the host reads the token. Read each row against two settings: a low-risk internal document store and a sensitive regulated environment. The main takeaway is that the same option can be acceptable in one setting and insufficient in the other, so confirm each choice against your own data classification and your integration's documented behavior.
| Design choice | Low-risk internal document store | Sensitive regulated environment |
|---|---|---|
| Token lifetime | Moderate lifetime may be acceptable if the host limits exposure to internal users; confirm the value your host issues by default. | Shorter lifetime set by policy and tested against long editing sessions, with refresh behavior documented and reviewed. |
| Scope to one file and one user | Scoping still recommended, since a token tied to one file limits accidental reuse across documents. | Required design goal: a token should authorize one file for one user and nothing else, verified in CheckFileInfo. |
| Per-session token issued at open | Simple to operate; a new token per editing session limits how long any single token remains useful. | Preferred pattern where the host can issue tokens at open time and revoke or expire them without manual cleanup. |
| Long-lived or reusable token | Can reduce friction for long sessions, but expands the window if a token is copied or logged. | Usually hard to justify; if used, pair with strict scope, logging rules and documented revocation. |
| Bearer Authorization header | Accepted where the host and proxy handle headers consistently; confirm the header is not written to access logs. | Preferred where supported, since headers are less likely to appear in browser history, referrers or shared links. |
| Access_token query parameter | Acceptable for compatibility with older hosts, with URL logging reviewed. | Avoid where possible, because URLs are often recorded in proxy logs, monitoring and browser history. |
| Host validates token on every WOPI call | Recommended baseline, so expired or mismatched tokens fail early. | Required, with validation tested for expired, altered and cross-file tokens before go-live. |
| Token generation in the host (for example Nextcloud) | Use the host's default issuance; confirm the Collabora integration version supports the token behavior you need. | Document who generates tokens, where the signing secret lives and how it is rotated, and confirm this with the integration's documentation. |
What a token should be scoped to
A WOPI access token is only as narrow as the claims behind it. Each card below is a dimension the host should bind into the token and then check again on every WOPI call, so that a leaked or replayed token opens one document for one person with the rights that person actually holds.
A single file ID
Bind the token to the one file identifier it was issued for. The WOPI request path carries the file ID, so the host should reject any request where the token's file claim and the requested file differ. Without this check, a token issued for a harmless document can be reused to open another file the same user can reach. Confirm that your host compares the identifiers exactly, including any version or path component your storage uses.
A single user identity
Carry one stable user identifier in the token and check it against the session that requested the editor. The identifier should come from your identity provider or the host's account record, not from a display name or a client-supplied field. Confirm how the host maps its user to the value Collabora receives as the user ID, because a mismatch here produces either wrong attribution in edits or broken access checks.
Permitted operations: view or edit
Decide at issue time whether the token grants view-only access or edit rights, and encode that decision as a separate claim. The host should map its own permission model onto this claim, so a user who can only read a file never receives a token that allows writes. Ask the vendor and your integration partner which WOPI operations each claim gates, and test that a view-only token cannot complete a save.
Group and role checks on the host
The host must decide who may open the editor and who may edit, using its own groups. In Nextcloud Office, administrators can limit which groups can use the editor and which can edit rather than only view. These limits are enforced on the host side, so the claims in each token must match the group outcome at the moment of issue. Re-check group membership on each token issue, and document how revoked group membership ends an open session.
Bearer header support and third-party token generation in Nextcloud
The main decision in this section is where the access token travels. In the default WOPI pattern the token is passed as a query parameter on the WOPI URL, which means it can end up in reverse proxy access logs, browser history, referrer headers and application logs. Where your Collabora Online version supports sending the token in an Authorization header with the Bearer scheme, you can move it out of the URL and reduce what intermediate systems record. Confirm in your deployed release whether Bearer header support is enabled for the WOPI calls your host makes, and whether the server accepts both forms during a transition. Then configure your reverse proxy and log formats to confirm that neither the query string nor the header value is written to logs in clear text, and test this with real sessions rather than assuming the setting took effect.
Nextcloud generates the tokens used when the Office app opens a document through a WOPI host, so the token design you specify on the Collabora side depends on the Nextcloud release and app version you run. Check how the installed Nextcloud Office app creates the token, what lifetime it assigns, and which user and file identifiers it embeds, against the Nextcloud Office configuration section of the admin manual and the release notes for your versions. Do not assume the defaults match your security requirements. Ask your team or partner to document the exact token fields, the expiry behavior, and how a token is refreshed for a long editing session, because these details decide whether a leaked token is useful to an attacker for minutes or for hours.
Test the whole chain before go-live. Open the same document as two different users, confirm that a token issued for one cannot open the other user's session or a different file, and check the proxy and application logs for stored token values. Repeat the test after every Nextcloud Office app update and every Collabora Online minor release, since token handling changes across versions. Record the tested versions and the results so that an upgrade has a reference point. If your integration is not Nextcloud, the same questions apply to whichever WOPI host issues the tokens.
How to set up token issuance and validation in a WOPI host
This sequence takes a WOPI host from undefined access to tokens that are issued per file and per user, expire quickly, and are checked on every WOPI call. The output is a host that refuses expired, reused and cross-file tokens and accepts requests only from known Collabora server addresses.
Define token claims and lifetime policy
Before writing code, the platform owner and the security lead agree on what each token carries: the file ID, the user identifier, the permissions granted (view or edit), an issue time, an expiry time and a unique token identifier. They also set a lifetime policy that is short enough to limit replay and long enough that a normal editing session does not break mid-document. Record the decision in the integration design so the issuing and validating code share one definition. Done means a written claims schema and lifetime rule that both developers and reviewers have signed off on.
Implement token issuance in the host
The host application, for example Nextcloud or a custom WOPI host, issues a token only after its own authorization check passes for the requested file and user. The token must be bound to exactly one file ID and one user, and the host should sign it with a key it controls and store the token identifier so it can be tracked. Issuance should also be logged. Done means a test user who lacks access to a file receives no token, and a user with access receives a token whose decoded claims match the schema from the previous step.
Validate file ID, user and expiry in CheckFileInfo
The WOPI host checks each incoming token on CheckFileInfo before returning any file metadata. The check confirms the signature, that the token has not expired, that the file ID in the URL matches the file ID in the token, and that the user matches. Requests that fail any check return an unauthorized response with no file details. Done means that calling CheckFileInfo with a valid token for file A and the URL for file B is refused, and an expired token is refused with the same result.
Apply the same checks to file content endpoints
Validation must not stop at CheckFileInfo. The endpoints that read file contents, write changes and manage locks each need the same token, file ID and expiry checks, because a client can call them directly once it has a token. Review every WOPI operation your host implements and confirm each one runs the validation function rather than a copy of it. Done means a code review or automated test shows that no file endpoint serves content without passing the shared check.
Configure Bearer header handling
Collabora Online and the host exchange the token in the request. Confirm the Authorization header format your Collabora version sends, and make the host accept the token from the place the protocol specifies, while rejecting tokens supplied in unexpected locations such as query strings where your logs could capture them. Check the exact behavior against the WOPI documentation and your Collabora release notes, since header handling is a detail to verify, not assume. Done means a capture of one live session shows the token transmitted where the host expects it, and a request with the token removed is refused.
Restrict WOPI requests to Collabora server addresses
Limit which network sources can call the WOPI endpoints. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers, and the host should use the same protocol, preferably HTTPS, for the Collabora server URL as for the host itself. Set this at the firewall, reverse proxy or host configuration, and confirm the address list matches your actual Collabora servers, including any load balancer in front of them. Done means a request to a WOPI endpoint from an address outside the list is refused even when it carries a valid token.
Test expired, reused and cross-file tokens
Run a negative test suite against a staging host. Use an expired token, a token used after it was intended to be single-use or after the session closed, a token issued for file A presented for file B, a token for user X presented as user Y, and a token with a modified signature. Each case must return a refusal and be recorded in the host logs. Repeat the suite after any change to the validation code. Done means every negative case is refused in the test run, and the results are saved with the integration design as evidence for the security review.
Security risks in token handling and how to reduce them
A WOPI access token is a bearer credential that grants access to one document, so anyone who holds it can act as the user it was issued for. The five risks below cover where tokens leak, how they get replayed, and where host-side checks are most often missing. Each card pairs a risk with a control you own, because Collabora Online does not enforce these checks on your WOPI host.
Token leakage through URLs and logs
WOPI tokens are often passed as query parameters, which means they can end up in reverse proxy access logs, browser history, referrer headers and application logs. Anyone who reads those logs can reuse a live token. Decide where the token travels, prefer the Authorization header with a Bearer scheme where your WOPI host and Collabora build support it, and configure log formats to redact query strings. Check your proxy and application logs for token values during testing, and confirm that the token-bearing requests use HTTPS end to end.
Replay after expiry
A token that stays valid long after a session ends lets a captured value open a document weeks later. Set short lifetimes at issuance in your WOPI host, and make the host reject tokens whose expiry has passed, regardless of what the client sends. Ask your Nextcloud or other host team to confirm how long tokens last, how they are renewed during long editing sessions, and whether a revoked user loses access before the token expires.
Token reuse across files
A token issued for one document must not open another. If the host accepts a token by user alone, or does not compare the file ID in the CheckFileInfo request with the file the token was issued for, one credential can reach many files. Validate that the file identifier in the request path matches the token's claims on every WOPI call, not only the first one. Test with two documents owned by one user to confirm the second request is refused.
Missing user binding
A token that identifies a file but not a user lets anyone holding it act with that file's permissions, including edit rights. Bind each token to the user ID, the permission level and, where your policy requires it, the group or share that granted access. In CheckFileInfo, return user metadata only for the bound user and reflect the bound permissions in UserCanWrite and related fields. Confirm that a read-only share cannot produce a token that edits.
Weak validation on the host
Collabora Online sends the token to your WOPI host, and the host alone decides whether the token is valid. Common gaps include skipping signature checks, accepting unsigned or expired tokens, and trusting claims without comparing them to stored state. Validate the signature or stored record, expiry, file ID, user ID and permissions on every request, and log rejected attempts. Have a separate tester attempt tampered, expired and cross-file tokens against your host before go-live.
Questions teams ask before designing Collabora Online access tokens
How much effort does access token design take for a Collabora Online integration?
The effort depends mostly on how your platform already controls access to files. A host with a clear permission model for each document can map tokens to that model with modest design work. A host with many storage backends, shared folders, guest users or nested permissions needs more time to define what a token may open, for how long, and for which action. The main drivers are the number of document entry points, the number of user roles that can open or edit a file, whether tokens already exist in your platform, and how many file types must be tested. Ask any partner to break the estimate into permission mapping, token issuing, token validation in CheckFileInfo, logging and test cases, so you can see which part drives the total.
Can an in-house team design Collabora Online access tokens without a partner?
Yes, if the team has experience building WOPI endpoints and working with the authorization code of the host platform. The work is mostly careful engineering: generating tokens with a clear lifetime, binding each token to one file and one user, reading the token from the request in the form your Collabora Online version expects, and rejecting requests that do not match. The risks are subtle. A token that works for one file may be accepted for another, expired tokens may still be honored by a cache, or an edit permission may be granted when only view was intended. Teams that build this in-house usually benefit from an independent review of the design and a test plan that includes negative cases. Nextcloud users may need less custom code, because the Nextcloud integration already handles much of the token flow.
What does token design need from host application developers?
Host developers own the decisions that tokens depend on, so their time is required early. They need to explain how permissions are stored, how group and share rules are evaluated, and where file identifiers come from. They also need to expose a CheckFileInfo handler or equivalent in the host, add token generation at the point where a user opens a document, and support a staging environment where Collabora Online can call back into the host. Plan for code review of the authorization path, access to logs that show each token issued and validated, and a short cycle of fixes after testing. If the host is a commercial product, check whether the vendor allows custom WOPI handling, because that determines where the work can be done.
How long does testing take for different host complexity levels?
Testing time follows the number of permission paths your host supports, so no single duration applies to every platform. A host with one storage backend, one group model and a small set of file types can be tested with a compact matrix. A host with several storage backends, shared links, guest access, external users and multiple Collabora Online servers needs a larger matrix that covers each combination of user, file, action and expiry. Ask for the test matrix in the proposal, including cases for expired tokens, tokens reused on another file, wrong user identifiers, view-only users attempting to save, and load balancer routing by WOPISrc. The matrix size gives you a more reliable way to compare proposals than a headline duration.
Can Collabora Online enforce token scoping on its own?
No. Collabora Online handles the editing session, but the WOPI host decides who may access a document and under what conditions. The host issues the access token, and the host checks it when Collabora Online calls back to fetch file information or contents. If the host accepts any token that is valid for the platform, the editor will open files that the user should not see. Collabora Online can help limit what a user does inside a session through integration-controlled settings, but scoping a token to one file and one user is an integration responsibility. Confirm each behavior against the WOPI documentation and your Collabora Online version before you rely on it in production.
What should a partner quote for token design include?
A useful quote states the scope in writing before work starts. DeployOpen works to fixed-scope agreements, so the quote should list the items being delivered, such as a token design document, the token issuing and validation code for the named host, a test matrix, test results, and handover notes. It should name the host version, the Collabora Online version, the environments covered, and what the client provides, such as access to staging systems and developers for review. Separate one-time design and build work from any recurring support. If a Collabora Online subscription is part of the plan, that cost is a separate line, and you should confirm which plan covers your user count. DeployOpen does not publish a price list, so the quote follows from the written scope.
Does production use of Collabora Online require a paid subscription?
Collabora describes CODE, its free edition, as suited to testing, home use or small teams and not recommended for production. For production, Collabora's pricing page lists a Business plan at 3 euros per user per month for up to 99 users, which includes long term support, a service level agreement, signed security updates and customer portal access. Organizations with 100 or more users are quoted an Enterprise plan with volume discounts, which adds integration support, customization services and roadmap input. Confirm the current terms with Collabora, because pricing and plan contents can change. Token design work does not depend on the plan, but the support and security updates you receive do affect how quickly you can respond to advisories that touch the integration.
Does Nextcloud need token settings beyond the WOPI allow list?
Yes. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of your Collabora servers and using the same protocol for both services, preferably HTTPS. Those network controls reduce who can reach the WOPI endpoints, but they do not replace token checks inside the host. Nextcloud Office also lets administrators limit which groups can use the editor and which groups can edit rather than only view. Those group settings should match the permission model used to issue tokens, so that a user who should only view a file does not receive an edit-capable token. Document the mapping between Nextcloud groups and token rights, then test it with a view-only account and an edit-capable account.
How DeployOpen scopes and delivers token design for your integration
Token design work starts with a written scope, not an open-ended engagement. DeployOpen agrees the scope, deliverables and timeline in writing before work begins. For access token design, that scope usually names the WOPI host or hosts involved, the Collabora Online version and deployment model, the token lifetime and scoping rules to be implemented in CheckFileInfo, whether Bearer header support is needed on your side, and whether third-party token generation in Nextcloud is part of the job. Confirm each of these with your team before the quote is requested, because they are the inputs that determine the effort. A quote follows from the written scope, and DeployOpen does not publish a price list.
The build happens inside your infrastructure. Token issuance and validation code, the Nextcloud-side configuration, test fixtures and runbooks are delivered into your own cloud accounts, data centers or air-gapped networks, under your repositories and secrets management. Ask for the deliverables list to name each artifact, including the token flow diagram, the validation test cases and the operator notes for rotating signing secrets. Where you request it, DeployOpen can also run security testing against the token flow, covering replay of expired or out-of-scope tokens, attempts to reuse a token for a different file or user, and checks that unknown hosts cannot obtain tokens. Agree the test scope and the findings format in the same written document, and confirm who receives remediation tickets.
Ongoing work can be covered by a retainer, if you want it. Token behavior changes when Collabora Online is upgraded, when Nextcloud changes its connector, or when you add a new WOPI host, so someone must own those checks after go-live. DeployOpen offers ongoing support, upgrades and continuous testing as retainers, which can cover re-running the token test suite on each Collabora Online minor release. Ask for the retainer terms in writing, including response expectations and what is excluded, and decide before go-live who on your side approves changes to token lifetimes and scoping rules.
