Why the Collabora Online admin console needs its own access controls
The Collabora Online admin console and its WebSocket endpoint sit outside the document editing path, so they need their own access controls even when editing traffic is tightly restricted. An operator who runs Collabora Online behind a reverse proxy for Nextcloud or another WOPI host may have locked down WOPI requests and still left administrative routes reachable by anyone who can reach the server. The reverse proxy is where this decision is made. The Nextcloud reverse proxy guidance lists /cool/adminws among the routes the proxy forwards to coolwsd, so a proxy that passes everything through will also pass administrative traffic. Before changing anything, confirm which routes your proxy forwards and which networks can reach each of them.
Teams need this work most when the same Collabora Online server serves more than one purpose. Typical cases include shared hosting for several tenants or departments, several people holding administrator access with different responsibilities, and regulated environments where administrative changes must be attributable to a named person. In each case, a single administrative action or a single leaked credential can affect every document session on the server, including sessions that belong to other WOPI hosts. The exposure grows with the number of people who hold access, so ask how many accounts can reach the console, whether each administrator has an individual account, and who approves a change to those accounts. Your answers determine how much of the control set below you need to build now and how much you can defer, and they should be written down before the proxy rules are changed.
Access control options for the admin console
The most direct control is to allow requests to /cool/adminws only from an administration network, such as a management subnet or a VPN address range, and to reject everything else at the reverse proxy. The Nextcloud reverse proxy guidance lists /cool/adminws among the routes the proxy forwards to coolwsd, so the restriction belongs in the proxy rule set that handles that path, not in the application. Because the rule runs before the request reaches coolwsd, a refused request never touches the admin interface.
- Rule scope: Match the admin path specifically so that normal document editing traffic on other routes is not affected.
- Source addresses: Use only the addresses of administrator workstations or a bastion host, and review them when staff or network paths change.
- Proxy behavior behind a load balancer: Confirm which address the proxy sees as the client, since a wrong trusted-proxy setting can make every request appear to come from the load balancer.
- Operator convenience: Administrators must be on the approved network or VPN to open the console, which is simple to explain but adds friction for remote support.
- Break-glass access: Keep a documented, tested path onto the admin network that works when the VPN itself is down.
Confirm with your network team how the admin network is defined and who can change the proxy rule.
A second option is to place the console behind an additional authentication step in front of the proxy route, so that a user must pass a separate check before the WebSocket connection is established. This can be an identity-aware access gateway, an SSO-backed proxy, or client certificates, depending on what your identity platform supports. The check is independent of the Collabora Online login, which means a compromised document session or a leaked console credential alone should not be enough to reach administration.
- Separate identity source: Use a group that only administrators belong to, so access can be reviewed and removed in one place.
- Multi-factor enforcement: Require a second factor at the gateway if your policy calls for it, and confirm that the gateway applies it to WebSocket upgrade requests as well as the initial page.
- Session handling: Set session lifetimes that suit administrative work, and confirm how the gateway behaves when a WebSocket connection stays open for a long time.
- Monitoring: Gateway logs record who authenticated and when, which complements the console's own record of actions.
- Operational cost: Each added layer is another system to patch, back up and troubleshoot during an outage.
Confirm which authentication methods your gateway supports for WebSocket traffic before committing to a design.
The most restrictive option is to deny the admin path at all times and open it only for a defined maintenance window, a change ticket, or an incident. The reverse proxy returns a refusal for /cool/adminws by default, and an administrator enables access through a reviewed change to the proxy configuration. This suits organizations that rarely use the console and want the attack surface to exist only when someone has a documented reason to use it.
- Change control: Record who enabled access, why, and when it was removed, using the same process you use for other production changes.
- Automation: Keep the deny rule and the temporary allow rule in version-controlled configuration so that reverting is a single, reviewed change.
- Time limits: Agree in advance how long access may stay open and who checks that it was closed.
- Break-glass access: The change path itself must work during an incident, so test it before you need it.
- Trade-off: Routine checks such as health review or quick user administration become slower, because each one needs an approved change.
Confirm with your change manager whether an emergency change path is acceptable under your current policy.
The three options are not mutually exclusive. Many teams combine a network restriction with an authentication layer and keep the path closed outside approved windows. The right combination depends on how often administrators use the console, how quickly they must respond to problems, and how much evidence your auditors expect for administrative access. A small team with one administrator may find a network restriction enough, while a regulated organization with several administrators often needs a gateway with strong authentication and a documented change process.
- Frequency of use: Frequent use favors network restriction and a gateway, while rare use favors keeping the path closed.
- Incident response: Make sure whichever option you choose still lets an on-call administrator reach the console within a time your incident process allows.
- Monitoring coverage: Each option produces different records, such as proxy logs, gateway logs or change tickets, so decide which records you will review.
- Review cadence: Revisit the allowed networks, identities and open windows on a fixed schedule.
- Testing: Verify each layer from an allowed and a disallowed location before relying on it.
Ask your security and operations teams to agree on the combination and document the break-glass path before deployment.
How to restrict /cool/adminws at the reverse proxy
This sequence limits the Collabora Online admin WebSocket route to approved administrator networks and strengthens the console credentials. It ends with tests from allowed and disallowed networks, each checked against the proxy log, so you have evidence that the control works.
Inventory the proxy routes
The team that operates the reverse proxy exports its current configuration and lists every location block or route that forwards traffic to coolwsd. Use the route list in the Nextcloud reverse proxy guidance as your reference, and confirm each route against the documentation for your Collabora Online version. Flag any route you cannot match to a known purpose for review. Done when you have a written list of routes and the upstream each one reaches.
Identify the admin WebSocket route
Find
/cool/adminwsin the list and confirm it is one of the routes the proxy forwards to coolwsd. This endpoint carries the admin console's WebSocket connection, so it deserves the same scrutiny as the console login. Record the exact match rule your proxy uses, such as an exact path or a prefix, because a broad prefix can match more paths than you intend. Done when the rule and its upstream are written down next to the route list.Restrict the route by source network
Add an allow rule for
/cool/adminwsthat permits only the administrator networks or jump hosts you name, and deny all other sources for that location. Keep the rule scoped to that exact path and leave other routes unchanged. Run your proxy's configuration syntax check, then reload the proxy. Done when the check passes and the rule is present in the file the proxy actually loads.Set strong administrator credentials
Confirm the admin console has an administrator account with a unique, long password stored in your secrets manager, and that no default or shared credentials remain. The way these values are set differs between packages, containers and Kubernetes, so confirm the exact mechanism in the Collabora Online documentation for your version. Limit the number of people who hold the password. Done when a login with any default or previous credentials fails and the new credentials succeed from an approved network.
Confirm WebSocket upgrade handling
Check that the proxy passes the WebSocket upgrade headers on this route. The admin console connects over WebSocket, and a route that drops the upgrade fails in ways that can look like a credential problem. Confirm that TLS for this route matches the protocol you use for the rest of the Collabora Online endpoints. Done when a browser session from an approved network opens the admin console and the connection stays open through the proxy.
Test access from an allowed network
From an approved administrator network, open the admin console through the proxy and sign in with the new credentials. Check the proxy access log for the request to
/cool/adminwsand confirm it returns the expected response and no proxy error. Note the source address the proxy recorded. Done when the login succeeds and the log entry shows an allowed source address.Test refusal from a disallowed network
From a network outside the allow list, send the same request to
/cool/adminws, then attempt the console login. Expect the proxy to refuse the request before it reaches coolwsd. Check the proxy log for a denied entry from that source, and confirm coolwsd records no login attempt from it. Done when the request is refused at the proxy, the denial appears in the log, and you have saved that log excerpt in your change record as evidence.
Setting and rotating administrator credentials
Administrator credentials are the first control on the admin console, and the controls that follow in this section depend on them. Each card covers one decision or routine, from how a credential is created and stored to how administrator access ends.
Set a strong, unique password
Use a long, unique, generated password for the admin console that is not reused from any directory account, shared vault entry or other service. Generate it with a password manager so that no person chooses it. Check that the value meets the length and character rules in your own policy. Confirm on your installed version whether the console limits repeated failed logins, and set your monitoring to alert on them.
Keep secrets out of configuration files
Admin credentials should not sit in plain text in server configuration, container images, Helm values committed to Git, CI logs or shared runbooks. Inject them at runtime from your secrets manager or an orchestrator secret, and restrict who can read the resulting files. Check that configuration backups and container inspection output do not expose the value. Rotate any credential that has already appeared in one of these places.
Rotate administrator passwords on schedule
Set a rotation interval in your policy, and also rotate after an administrator leaves, after a suspected exposure and after any support engagement that used console access. Plan each rotation as a short change: update the secret store, restart the service if your release requires it, and test the new credential. Then confirm that the old one is refused. Record the date and the person who made the change.
Limit the number of administrators
Grant console access to a small set of named administrators, and keep one documented break-glass account whose secret is held under dual control. Keep console rights separate from document users and from integration service accounts, so that a Nextcloud or other WOPI host service account can never reach the admin console. Review the list at an interval set by your policy and compare it with your current staff directory.
Remove access when staff leave
Make administrator offboarding a separate step in your leaver process, not something that happens only when the directory account is disabled. Remove the console account, revoke any personal copies of the password, and rotate every shared secret the person could read. Review console and reverse proxy logs for activity before the departure date. Check that proxy allow rules do not depend on a personal workstation address.
Confirm the authentication model
How the admin console authenticates administrators can differ between Collabora Online releases and packaging methods, so do not write procedures from memory or from older guides. Read the Collabora documentation for the exact version you run, note the supported authentication method and any credential settings it lists, and test a login on a non-production instance first. Repeat this check after each upgrade.
Logging administrator actions for review
Administrator access needs an audit trail because the admin console can change how the whole server behaves, and a compromised or misused session would otherwise leave no record of who connected, from where, or what they changed. Logging is the control that lets you answer those questions after the fact and detect misuse early. Treat the reverse proxy log and the coolwsd log as separate evidence sources: the proxy shows every request to /cool/adminws with its source address and timing, while coolwsd records what the server did with the session. Before you rely on either, confirm with your installed version which administrator actions coolwsd writes to its log, at what level, and with which fields, since logging behavior differs between branches and this page does not promise specific log fields.
Forward both streams to a central store that your security team controls and that the Collabora host cannot silently rewrite. Decide the retention period with your compliance owner, set the proxy to log the admin path with the client address and authenticated identity where your authentication layer provides it, and confirm that the logs carry accurate timestamps so events from the proxy and coolwsd can be correlated. Restrict who can read these logs, because they contain client addresses and session activity. Test the pipeline on purpose: open an admin session from an allowed address, make a harmless change, and confirm the event appears in the central store with enough detail to reconstruct it. Also test a denied connection so you know refused attempts are recorded too.
Plan a review routine rather than a one-off setup. Someone should check the admin-path entries on a set schedule and whenever an alert fires, and they should be able to compare the list of accounts with admin rights against the people who actually connected. Where your logs do not capture a change you need to account for, document that gap and the compensating control, such as a configuration change record kept in your own version control. Ask Collabora or your DeployOpen contact to confirm the exact log lines for your version before you write detection rules against them, so your alerts match what the server actually emits.
Security and operational risks of an exposed admin console
The admin console controls how the Collabora Online server runs, so a weak entry point affects every document session it serves. The four risks below map to the controls in this setup section, and each card names what to check in your own environment.
Open admin WebSocket on the internet
The /cool/adminws path is one of the routes a reverse proxy forwards to coolwsd. If the proxy passes it through for any client, anyone who can reach the host can attempt to open the administrative channel. Restrict the path at the reverse proxy so only administrator networks or bastion hosts can reach it, and deny it for all other sources. Confirm the rule with a request from an outside network, which should be refused. Review the proxy configuration after every upgrade, since templates may add the route back.
Shared administrator credentials
When several operators use one administrator password, no log entry can show who changed a setting, and removing one person's access means rotating the secret for everyone. Give each administrator a named account, store the credential in your secrets manager, and require strong, unique passwords. Confirm which authentication options your Collabora Online version offers for the admin console, and document who holds each credential and how it is rotated when someone leaves the team.
Missing administrator audit trail
Without a record of who connected to the admin console and what they changed, an incident review cannot separate a legitimate configuration change from a misuse of access. Forward coolwsd logs and reverse proxy access logs to your central log platform, keep them outside the Collabora host, and set retention to match your policy. Test that a sample administrator action appears in the central store with a timestamp and source address before you rely on it.
Unrecorded changes during incidents
During an outage or suspected compromise, operators often edit settings directly to restore service, and those edits are easy to lose or misattribute. Set a rule that every change, including emergency ones, is made through your configuration management tool and recorded in a ticket. Keep the proxy and coolwsd configuration in version control so a diff shows what changed and when. After the incident, compare the running configuration with the approved baseline before closing the ticket.
Questions teams ask before protecting the admin console
What does it cost to protect the Collabora Online admin console?
The cost depends on how much of the restriction work your own team already covers and how many layers you need. The work usually includes a credential decision, a reverse proxy rule for /cool/adminws, network range definitions, a test pass from inside and outside the allowed networks, and log forwarding. Most of this is one-time effort, while credential rotation, reviewing access lists and reading logs recur. Ask any partner for a written scope that lists each of these items and who performs each one, so you can compare it with your internal effort. No figure is given here because no researched price or effort figure applies to this work.
What drives the effort of restricting the admin WebSocket endpoint?
Effort rises with the complexity of your reverse proxy setup. A single proxy with a clear route table is far simpler than a chain of load balancers, ingress controllers and a WOPI host that also sits behind its own proxy. Other drivers include how many administrators need access, whether they reach the console through a VPN or bastion, whether you use one Collabora Online server or several, and whether the rule must be duplicated across environments. Teams that already manage proxy configuration as code usually find the change smaller to review and test.
How long does it take to deploy and test an admin console restriction?
The change itself is small, but testing takes longer than writing it. Plan time for a staging test that confirms the admin WebSocket path is refused from unapproved addresses, accepted from approved administrator addresses, and still forwarded correctly to coolwsd. Then confirm that normal document editing from your WOPI host is unaffected. Duration depends on your change control process and how many environments you maintain, so confirm the schedule with your team or partner in writing rather than relying on a general estimate.
What does our team need to provide for this work?
You need to provide the network ranges or identity groups that should reach the admin console, access to the reverse proxy configuration, and a destination for logs such as a SIEM, log platform or central syslog host. You also need the names of the people who approve access changes and who will receive alerts. Without these inputs, the restriction either blocks legitimate administrators or leaves gaps. Ask the implementer to list each input in the scope document so responsibilities are clear before work starts.
Can our own team protect the admin console without outside help?
Yes, if you already operate your reverse proxy and can run a test plan against your Collabora Online server. The Nextcloud administration documentation describes how to route the /cool/adminws path through a reverse proxy, and the work is primarily configuration and verification. Outside help is most useful when you need an independent review of exposure, a documented test record for an assessment, or help connecting audit logs to your monitoring stack. Decide based on the staff time available and whether an independent check is required by your governance process.
Does the admin console restriction need to change after a Collabora Online upgrade?
Usually the core rule stays the same, but you should retest after every upgrade. Each new branch or minor release can change routes, default settings or the way the proxy and server negotiate WebSocket connections. Subscribe to Collabora's security advisories and release notes so you know when a patch affects the admin path. Include the admin console test in your upgrade checklist, and keep the proxy configuration under version control so the previous working state is easy to restore.
Which audit logs should we keep for administrator actions?
Keep records of who connected to the admin console, when, from which address, and which administrative actions they performed, along with failed logins and refused connections at the proxy. Confirm with your Collabora Online version which events the server writes and whether they include the administrator identity. Send both proxy and server logs to a location your security team controls, and set retention to match your internal policy and any regulatory requirement that applies to you. Verify the logs by performing a test login and checking that each expected entry appears.
How DeployOpen scopes and delivers admin console hardening
DeployOpen agrees the scope of admin console hardening in writing before any work starts. The written scope names the Collabora Online hosts in play, the reverse proxy or ingress that fronts them, the networks that should reach /cool/adminws, the people who will hold administrator credentials, and where the audit logs will be kept. Each item is a decision the client confirms, not an assumption DeployOpen makes. The scope also records who owns the reverse proxy rules and who signs off on the allowed source ranges, because those are the settings most often changed later by someone who was not in the original discussion.
The configuration is built and run inside your own infrastructure, in your cloud accounts, data centers or restricted network, using your existing change process. DeployOpen works through the proxy rules that restrict the admin WebSocket path, the administrator authentication setup and the logging pipeline, and documents each change so your operations team can repeat it. Verification is part of the delivery. Reachability tests are run from networks that should be allowed and from networks that should be refused, and the results are recorded against the scope so you can see exactly what was tested and what passed. Your own team should repeat these tests after any proxy or network change.
Upgrades and ongoing checks are handled through a retainer where both sides agree to one. A retainer can cover re-running the reachability tests after Collabora Online updates, reviewing proxy rules when the ingress changes, and checking that audit logs are still being written. Ask any partner, including DeployOpen, to state in the quote which of these tasks are included, how often they recur, and who approves a change to the allowed source ranges. Those answers determine whether the hardening stays in place after the initial project closes.
