What is JWT and how this technology protects your documents

There are ways to protect files actively – using encryption, watermarks, restrictive access permissions. But document security doesn’t end there. Read this post to discover JWT, an important access protection tool enabled by default in ONLYOFFICE since version 7.2.

What is JWT

JSON Web Token (JWT, pronounced as /dʒɒt/) is an open standard for secure online information exchange used mainly for two purposes – authorization and data transfer.

A compact JSON object contains the authentication information and provides the ability to verify legitimate users of the service, when applied in web applications. In a nutshell, it helps the application confirm that the sender of the information is who they claim they are.

JWT is a self-contained object in a form of a string that consists of three parts: header, payload, and signature. Header contains the information about the token and how the signature is generated, payload contains the claims about the user necessary to grant them permission for access, and signature validates the user.

The token can be signed with a secret key that helps validate the origin of transferred data.

How ONLYOFFICE uses security tokens

In ONLYOFFICE, JWT secures data stream between the editor and the user. It helps verify users who enter the editing sessions in Docs and attempt to perform certain actions in documents.
For each HTTP request from and to ONLYOFFICE Document server, a token is generated and added to the parameters.

Here, different JWTs are generated for different user actions. While the tokens are signed with the same secret in each case, the information that helps authorize the input differs. For example, a separate token is created for opening the editor, for inserting an image into the file, for opening document version history, etc.

For instance, to add a PNG image to the file hosted on www.example.com, the following parameters will be included in the token:

{
    "fileType": "png",
    "url": "https://example.com/url-to-example-image.png"
}

And this is how the sample token will look like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWxlVHlwZSI6InBuZyIsInVybCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vdXJsLXRvLWV4YW1wbGUtaW1hZ2UucG5nIn0.FXuC3GUvPq3japwyzo4i-utUe3g1rfSDt1ytuK_VyCc

To sign the JWT, a custom secret is used in each sharing service where ONLYOFFICE Docs is integrated.

Where to retrieve the secret key

In previous versions of ONLYOFFICE Docs, JWT secret had to be generated by an administrator of the host service (i.e. Nextcloud) and submitted to ONLYOFFICE Document Server manually via settings to enable it.

Starting from version 7.2, JWT is enabled by default. When ONLYOFFICE Docs is installed and launched, a random secret is automatically generated and just needs to be added on the side of the host application.

Note: If you are already using ONLYOFFICE Docs with JWT, the original key will remain in your setup. The exception is Docker installation: if in the installed Document Server the env variables are not set or the JWT parameters are not defined, a random secret will be generated after updating.

Linux and Windows server installation

You can obtain the default JWT secret from the local.json file using the following path:

For Linux: /etc/onlyoffice/documentserver/local.json

For Windows: %ProgramFiles%\ONLYOFFICE\DocumentServer\config\local.json

You can find the secret in services.CoAuthoring.secret.browser.string parameter.

Docker installation

If ONLYOFFICE Docs is installed using Docker, run the following script to obtain the secret:

sudo docker exec f00ad6e66a40 /var/www/onlyoffice/documentserver/npm/json -f /etc/onlyoffice/documentserver/local.json 'services.CoAuthoring.secret.session.string'

To replace the default secret with a custom key, read the documentation.

Individual instructions for each installation method will also be available at the launch page of ONLYOFFICE Docs after installation.

Where is JWT available?

JWT is supported in almost all of the official ONLYOFFICE integration apps:

• Nextcloud
• ownCloud
• Alfresco
• Moodle
• Mattermost
• Chamilo
• HumHub
• Confluence
• Plone
• Strapi
• Liferay
• Jira
• Nuxeo
• Redmine
• WordPress
• and others

You can browse all available integrations on our website and find token configuration guides on the corresponding GitHub pages or Help Center.

If you want to create an ONLYOFFICE integration app for your own app, it is possible to add support for the security tokens using our API guidelines.