Eric Doughty-Papassideris
139 lines
5.8 KiB
Markdown
139 lines
5.8 KiB
Markdown
# Twake Drive - How to enable plugins
|
|
|
|
Plugins, or applications, are configured in the backend's json configuration file `/backend/node/config/{env}.json`:
|
|
|
|
```json
|
|
{
|
|
"applications": {
|
|
"grid": [ ],
|
|
"plugins": [ ]
|
|
}
|
|
}
|
|
```
|
|
|
|
The environment variable `APPLICATIONS` can be used to override the configuration file, eg:
|
|
|
|
```sh
|
|
APPLICATIONS='{ "grid": [ ... ], "plugins": [ ... ] }'
|
|
```
|
|
|
|
*Note: the `applications` key is the root of the environment variable's json.*
|
|
|
|
## Application grid entries
|
|
|
|
Links in top right drop down application grid can be configured in the `applications.grid` array, eg:
|
|
|
|
```json
|
|
{
|
|
"applications": {
|
|
"grid": [
|
|
{
|
|
"name": "Tmail",
|
|
"logo": "/public/img/grid/tmail.png",
|
|
"url": "https://tmail.linagora.com/"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Plugins
|
|
|
|
*Currently all applications are automatically active for all companies (subject to change).*
|
|
|
|
Plugins are defined as entries under the `applications.plugins` array, with at least the following properties:
|
|
|
|
- `id` is mandatory and must be unique to each plugin
|
|
- `internal_domain` is the internal domain of the plugin's server, it must be the same as the one in the docker-compose.yml file for ex. or resolvable and accessible to the Twake Drive backend server.
|
|
- `external_prefix` is the external URL prefix of the plugin exposed by the backend and proxied to the `internal_domain`.
|
|
- `api.private_key` is the shared secret used by the plugin's server to authentify to the backend
|
|
|
|
### Proxying
|
|
|
|
- The frontend server in development (next), or nginx in production, should relay all requests to `/plugins/*` to the same url on the Twake Drive backend
|
|
- The Twake Drive backend will proxy all requests below `external_prefix` to the same url at `internal_domain` intead for the matching plugin
|
|
|
|
### Application authentification
|
|
|
|
- To send API commands to Twake Drive, the application must first obtain a JWT token. This is obtained by `POST https://[backend]/api/console/v1/login`, with a JSON body containing the shared `{ id, secret: api.private_key }`, and an `Authorization` header with as Basic auth the base64 encoded pair in the format `id:api.private_key`. See [refreshToken](https://github.com/linagora/twake-drive/blob/main/tdrive/connectors/onlyoffice-connector/src/services/api.service.ts). The response should be in the format `{resource: {access_token: { value }}}`. The resulting token expires and should be periodically renewed.
|
|
|
|
- To authenticate further API requests, add the returned token to the headers as `Authorization: Bearer $token`.
|
|
|
|
### User initiated notifications to a plugin
|
|
|
|
`POST /companies/:company_id/applications/:app_id/event`
|
|
|
|
Sending a request of this format to the backend will proxy that request after signing it to `plugin.api.hooks_url`. Accepts JSON body with fields `type`, `content` and optionally `name`. Adds the header `X-Tdrive-Signature` containing a hex encoded sha256 of the json body hmac signature with `plugin.api.private_key`, and returns the remote's response to the user.
|
|
|
|
The payload sent to the hooks server includes: `{ type, name, content, connection_id, user_id, company_id, workspace_id}` (see `ApplicationHooksService.notifyApp`).
|
|
|
|
## File plugins
|
|
|
|
The configuration in `plugin.display.tdrive.files` allows a plugin to hook file creation, preview and edition.
|
|
|
|
Here is (an incomplete) example based of the Only Office connector plugin.
|
|
|
|
```json
|
|
{
|
|
"applications": {
|
|
"plugins": [
|
|
{
|
|
"id": "tdrive_onlyoffice",
|
|
"internal_domain": "http://plugins_onlyoffice:5000/",
|
|
"external_prefix": "/plugins/onlyoffice/",
|
|
"api": { "private_key": "apisecret" },
|
|
"display": {
|
|
"tdrive": {
|
|
"version": 1,
|
|
"files": {
|
|
"editor": {
|
|
"preview_url": "/plugins/onlyoffice/?preview=1",
|
|
"edition_url": "/plugins/onlyoffice/",
|
|
"empty_files": [
|
|
{
|
|
"url": "/plugins/onlyoffice/assets/empty.docx",
|
|
"filename": "Untitled.docx",
|
|
"name": "ONLYOFFICE Word Document"
|
|
}
|
|
],
|
|
"extensions": [ "docx", "odt" ]
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"identity": {
|
|
"code": "only_office",
|
|
"name": "Only Office",
|
|
"icon": "/plugins/onlyoffice/assets/logo.png",
|
|
"description": null,
|
|
"website": "http://twake.app/",
|
|
"categories": [],
|
|
"compatibility": ["tdrive"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Creation
|
|
|
|
The field `editor.empty_files` can contain a list of template empty files editable by this plugin. The files must be hosted below the url in `external_prefix` (eg. `"/plugins/onlyoffice/"`). The backend will proxy all requests below `external_prefix` to the same url at `internal_domain` intead.
|
|
|
|
The file will then be downloaded by the browser from that URL, added to the current folder by Twake Drive, and opened in the provided editor.
|
|
|
|
### Preview and Editing
|
|
|
|
When a user requests a preview and then possibly to edit the file, an IFrame is opened and pointed to `files.editor.preview_url` or `files.editor.edition_url`, with the following query parameters:
|
|
|
|
- `token`: a JWT that can be used to authenticate as the user when calling the Twake Drive API
|
|
- `workspace_id`, `company_id`: Identifiers of the respective items
|
|
- `file_id`: External file identifier
|
|
- `drive_file_id`: Optional internal (to Twake Drive) file identifier
|
|
|
|
In the case of the OnlyOffice application, these URLs are pointing to the connector plugin, which then proxies back and forth with the OnlyOffice document server.
|
|
|
|
### Example: OnlyOffice plugin
|
|
|
|
The [OnlyOffice connector plugin](https://github.com/linagora/twake-drive/tree/main/tdrive/connectors/onlyoffice-connector) is an example of plugin. It's readme includes an example configuration for the backend.
|