guideExport to Word On-Premises authorization

To enable authorization, set up the SECRET_KEY environment variable during the installation.

If the SECRET_KEY variable is set, then all requests must have a header with a JWT (JSON Web Token) signed with this key. The token should be passed as a value of the Authorization header for each request sent to the Export to Word REST API.

If you do not set up any SECRET_KEY during the installation, then Export to Word On-Premises will not require any headers with tokens when sending requests to the Export to Word REST API. However, we do not recommend skipping authorization when running Export to Word On-Premises in a public network.

# Generating the token

We highly recommend using the libraries listed on jwt.io to generate the token. The token is considered valid, when:

  • it is signed with the same SECRET_KEY as passed to the Export to Word On-Premises instance,
  • it was created within the last 24 hours,
  • it is not issued in the future (e.i. the iat timestamp cannot be newer than the current time),
  • it has not expired yet.

The tokens for the Export to Word On-Premises do not require any additional claims, such as the environment ID (which is specific for Collaboration Server On-Premises), so you can create the token with an empty payload.

If your use case involves sending requests from your backend server, then you can generate JWT tokens locally, as it is done in our request example.

In the case of editor plugins or other frontend usages, you should create a token endpoint, that returns a valid JWT token for authorized users. Here you can find an example of an token endpoint implementation.

# Using editor plugins

The plugin for CKEditor 5 will automatically request the token from the given tokenUrl variable and will set the Authorization header when making an export request. Refer to the CKEditor 5 configuration guide for details on adding the Export to Word feature to your WYSIWYG editor!

# Request example with an Authorization header

The following example presents a request that generates a valid JWT token and sets it as an Authorization header:

const fs = require( 'fs' );
const jwt = require( 'jsonwebtoken' );
const axios = require( 'axios' );

const secretKey = 'secret';

const token = jwt.sign( {}, secretKey, { algorithm: 'HS256' } );

const data = {
   html: "<p>I am a teapot</p>",
   css: "p { color: red; }",
};

const config = {
   headers: {
      Authorization: token
   },
   responseType: 'arraybuffer',
};

axios.post( 'http://localhost:8080/v1/convert', data, config )
   .then( response => {
      fs.writeFileSync('./file.docx', response.data, 'binary');
   } ).catch( error => {
      console.log( error );
   } );

Please refer to the Export to Word REST API documentation to start using the service.

Note: If you use API clients like Postman or Insomnia, then set the JWT token as an Authorization header in the Headers tab. Do not use the built-in token authorization as this will generate invalid header with a Bearer prefix added to the token.