Extended CE: Zotero Integration

Zotero Integration

The Zotero integration feature allows you to import your Zotero My Library or individual Group Libraries to create a read-only .bib file that can be synchronized with your Zotero account. For details, refer to the Overleaf documentation.

Please note that the CE+ implementation still lacks what is called "advanced reference search" in the upstream implementation. Currently, it is only possible to bulk-import references to create a non-editable .bib file. Importing individual references into editable .bib files is not yet implemented.

To enable Zotero integration in CE+, the site administrator must register an OAuth application with Zotero to obtain a Client Key and Client Secret, and define the following environment variables:

ZOTERO_CLIENT_KEY=xxxxxxxxxxxxxxxxxxxx
ZOTERO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxx

Additionally, zotero must be added to the ENABLED_LINKED_FILE_TYPE environment variable:

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url,zotero

Zotero authorization tokens are stored in MongoDB in encrypted form. By default, a random encryption password is generated on the first startup and stored in the following file:

/var/lib/overleaf/data/.token-cipher.json

Note: This file is also used by default to store the encryption password for GitHub authorization tokens.

Once this file has been created, keep it safe and do not delete it. Otherwise, all users whose authorization tokens were encrypted with the password stored in this file will need to reconnect their Zotero accounts.

Technical details

If necessary, you can create this file manually. It has the following format:

{
  "cipherLabel": "OL_CEP-v3",
  "cipherPasswords": {
    "OL_CEP-v3": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "2026.7-v3": "yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy"
  }
}

In most cases, a single password is sufficient.

The cipherLabel field specifies which entry from cipherPasswords is used to encrypt newly created tokens. The label format is almost arbitrary: it must not contain a colon (:), and it must end with the suffix -v3.

You can change the default location of the file using environment variables:

• ZOTERO_TOKEN_CIPHER_FILE or TOKEN_CIPHER_FILE
  • Specifies the location of the password file. If both are defined, ZOTERO_TOKEN_CIPHER_FILE takes precedence.

Example:

ZOTERO_TOKEN_CIPHER_FILE=/var/lib/overleaf/data/.zotero-token-cipher.json

Alternatively, you can define the encryption password directly using environment variables instead of a file:

• ZOTERO_TOKEN_CIPHER_PASSWORD or TOKEN_CIPHER_PASSWORD
  • Specifies the encryption password. If both are defined, ZOTERO_TOKEN_CIPHER_PASSWORD takes precedence.
  • If either of these variables is defined, the password file is ignored.
• ZOTERO_TOKEN_CIPHER_LABEL or TOKEN_CIPHER_LABEL
  • Specifies the label associated with the encryption password. If both are defined, ZOTERO_TOKEN_CIPHER_LABEL takes precedence.
  • Defaults to OL_CEP-v3.