Skip to main content

​
Prerequisites

Before installing the OnlyOffice Control, ensure you have:
  • An ASP.NET Web Forms project targeting .NET Framework 4.8
  • Access to an OnlyOffice Document Server instance
  • The OnlyOffice Document Server API URL and JWT secret
Make sure your OnlyOffice Document Server is properly configured with JWT enabled for secure communication.

​
Installation Steps

1

Copy the Controls Folder

Copy the entire Controls/OnlyOfficeEditor folder to your ASP.NET Web Forms project root directory.Your project structure should look like this:
YourProject/
├── Controls/
│   └── OnlyOfficeEditor/
│       ├── OnlyOfficeEditor.ascx
│       ├── OnlyOfficeEditor.ascx.cs
│       ├── OnlyOfficeEditor.js
│       ├── OnlyOfficeEditor.css
│       ├── OnlyOfficeHandler.ashx
│       ├── OnlyOfficeHandler.ashx.cs
│       └── OnlyOfficeJwt.cs
├── Default.aspx
└── Web.config
2

Configure Web.config (Optional)

If you plan to upload large documents, configure the file upload limits in your Web.config:
Web.config
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.web>
    <compilation debug="true" targetFramework="4.8" />
    <!-- Increase max request length to 150MB (in KB) -->
    <httpRuntime targetFramework="4.8" 
                 maxRequestLength="153600" 
                 executionTimeout="3600" />
  </system.web>

  <system.webServer>
    <security>
      <requestFiltering>
        <!-- Increase max content length to 150MB (in bytes) -->
        <requestLimits maxAllowedContentLength="157286400" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>
The maxRequestLength is in kilobytes, while maxAllowedContentLength is in bytes.
3

Create Uploads Directory

The control stores uploaded and edited documents in ~/App_Data/uploads. This directory is created automatically, but you can create it manually:
YourProject/
└── App_Data/
    └── uploads/
Ensure the IIS application pool identity has write permissions to the App_Data folder.
4

Configure OnlyOffice Settings

Open Controls/OnlyOfficeEditor/OnlyOfficeEditor.ascx.cs and update the configuration properties:
OnlyOfficeEditor.ascx.cs
// URL of the OnlyOffice Document Server API
public string OnlyOfficeApiUrl { get; set; } = "https://your-server.com/web-apps/apps/api/documents/api.js";

// JWT secret key - must match your OnlyOffice server configuration
public string JwtSecret { get; set; } = "your-secret-key";

// Public base URL of your application
public string PublicBaseUrl { get; set; } = "https://your-app.com";
OnlyOfficeApiUrl: This is the URL to the OnlyOffice Document Server API JavaScript file. If your OnlyOffice server is at https://docs.example.com, the API URL would be https://docs.example.com/web-apps/apps/api/documents/api.js.JwtSecret: This is the JWT secret configured in your OnlyOffice Document Server’s local.json configuration file under services.CoAuthoring.secret.session.string.PublicBaseUrl: This is the public-facing URL of your ASP.NET application. OnlyOffice Document Server must be able to reach this URL to download documents and send callbacks.
5

Verify Installation

Build your project to ensure there are no compilation errors:
# In Visual Studio
Build > Build Solution (Ctrl+Shift+B)
If you encounter any compilation errors, verify that:
  • All files are properly copied
  • The namespace matches your project
  • .NET Framework 4.8 is targeted

​
Configuration Options

​
JWT Secret Management

For production environments, it’s recommended to store the JWT secret in a secure location rather than hardcoding it: 
<configuration>
  <appSettings>
    <add key="OnlyOffice:ApiUrl" value="https://your-server.com/web-apps/apps/api/documents/api.js" />
    <add key="OnlyOffice:JwtSecret" value="your-secret-key" />
    <add key="OnlyOffice:PublicBaseUrl" value="https://your-app.com" />
  </appSettings>
</configuration>

​
Network Configuration

If your OnlyOffice Document Server uses self-signed SSL certificates, the control includes certificate validation bypass. For production, configure proper SSL certificates.
The control uses TLS 1.2 for secure communication: 
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls;

​
Namespace Configuration

The default namespace is OnlyOfficeControl.Controls.OnlyOfficeEditorBundle. If you need to change it:
  1. Update the namespace in all .cs files
  2. Update the Inherits attribute in .ascx files
  3. Rebuild the project

​
Troubleshooting

Verify the control is properly registered on your ASPX page:
<%@ Register Src="~/Controls/OnlyOfficeEditor/OnlyOfficeEditor.ascx" 
             TagPrefix="oo" 
             TagName="Editor" %>
This usually means:
  • The OnlyOfficeApiUrl is incorrect or unreachable
  • CORS is not properly configured on the OnlyOffice server
  • The OnlyOffice server cannot reach your DocumentUrl (firewall/network issue)
Ensure:
  • The JwtSecret matches exactly with your OnlyOffice server configuration
  • JWT is enabled on the OnlyOffice Document Server
  • The secret is not empty or whitespace
Check:
  • Web.config has proper file size limits configured
  • IIS application pool identity has write permissions to App_Data
  • The uploads folder exists and is writable
Verify:
  • The PublicBaseUrl is publicly accessible from the OnlyOffice server
  • The OnlyOffice server can reach your application (no firewall blocking)
  • The CallbackUrl is properly generated

​
Next Steps

Quick Start

Learn how to use the OnlyOffice Control in your application

Build docs developers (and LLMs) love

Get started for freeTalk to us