README

WOPI Bundle

A Symfony bundle to facilitate the implementation of the WOPI endpoints and protocol.

Description

The Web Application Open Platform Interface (WOPI) protocol let you integrate Office for the web with your application, but also other software like Collabora Online

This bundle targets the integration with Collabora Online, for now.

In the future, this bundle may achieve a validation for an usage with Office For The Web.

Integration of Collabora Online

Collabora Online

Overview for WOPI protocol

wopi

Office for the web platforms:

Installation

composer require champs-libres/wopi-bundle

Usage

This bundle provides the basic implementation of the protocol into Symfony. But there are many ways to:

store documents in an application;
secure the protocol
and manage permission, according to your own business logic.

Therefore, this bundle does not provide a specific implementation of the WOPI protocol described through a basic interface from the champs-libres/wopi-lib bundle.

So, this bundle provides:

The routes that the WOPI protocol needs, which starts with /wopi path (required by the WOPI protocol);
A controller to for the WOPI routes;
And an implementation for the Wopi logic, which will re-use some of your logic to manager permission, document, etc.

Some vocabulary:

Wopi host: the app which implements this bundle;
Wopi client: Collabora Online (or Office 365), which will use the endpoint provided by your app (the host)
Editor: Collabora Online (or office 365). A synonym for Wopi client.

These are steps to integrate the wopi bundle in your application:

Start an editor / your wopi client for development

You will find a free collabora online with the CODE project: CODE.

⚠️ the editor must have access to your app, with the same domain name as the browser will open your app.

If you use docker and docker-compose, you can achieve this by manipulating your /etc/hosts file:

# docker-compose.yaml

services:
    app:
        # your php / symfony application
        # we assume that your app listen **inside the container** on the port 8001 (no port mapping required between inside and
        # outside of the container)
        # ...
    collabora:
        image: collabora/code:latest
        environment:
            - SLEEPFORDEBUGGER=0
            - DONT_GEN_SSL_CERT="True"
            - extra_params=--o:ssl.enable=false --o:ssl.termination=false
            - username=admin
            - password=admin
            - dictionaries=en_US
            - aliasgroup1=http://nginx:8001
        ports:
            - "127.0.0.1:9980:9980"
        cap_add:
            - MKNOD
        links:
            - app

# /etc/hosts

127.0.0.1 app collabora

With this config, you should be able to reach collabora using http://collabora:9980, and your app through http://app:8001. You must use the latter to access your app during debugging collabora features.

Configure this bundle

# app/config/package/wopi.yaml

wopi:
    # this is the path to your server.
    # note: the wopi client (Collabora) must be able to your app **using the same domains as your browser**
    server: http://collabora:9980

Create your document entity

Each document edited should be an entity which implements Document.

Create your document manager

Your manager will implements DocumentManagerInterface.

This DocumentManager will handle the document logic into your application. It provides methods for writing the document, and extract some information from it.

You can read an implementation here.

Create your logic for access token

access_token are created by your app, when it will open the editor page (spoiler: the editor page will be an iframe). The wopi host (your application) will receive this access token on every request made by the client. Each token should have a duration of 10 hours.

You can choose your own logic. But JWT can ease your life.

Some working configuration using LexikJWT

An easy way to authenticate your request is to use JWT (Json Web Token). This can be achieved easily with LexikJWTAuthenticationBundle.

Create a firewall and configure access control for url starting by /wopi:

# config/package/security.yaml
security:
    firewalls:
        wopi:
            pattern: ^/wopi
            stateless: true
            guard:
                authenticators:
                    - lexik_jwt_authentication.jwt_token_authenticator
    access_control:
        # ...
        - { path: ^/wopi, roles: IS_AUTHENTICATED_FULLY }
        # ...

Configure lexik:

# config/package/lexik_jwt_authentication.yaml
lexik_jwt_authentication:
    # required for wopi - recommended duration for token ttl
    token_ttl: 36000

    # required for wopi: the token is in query, with `?access_token=<your_token>`
    token_extractors:
        query_parameter:
            enabled: true
            name: access_token

See a working implementation: https://gitea.champs-libres.be/Chill-project/chill-skeleton-basic

Provide information about your user

Implements UserManagerInterface to provide information about your users.

This information should be extracted through access token.

Some working implementation

Provide information about the permissions / authorization

Implements AuthorizationManagerInterface to provide information about the permissions on the given Document.

Some working implementation

Bind all the services

This bundle will require the implementation to be name according to the interface.

Some example:

namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use ChampsLibres\WopiBundle\Contracts\AuthorizationManagerInterface;
use ChampsLibres\WopiBundle\Contracts\UserManagerInterface;
use ChampsLibres\WopiLib\Contract\Service\DocumentManagerInterface;
use Chill\WopiBundle\Service\Wopi\AuthorizationManager;
use Chill\WopiBundle\Service\Wopi\ChillDocumentManager;
use Chill\WopiBundle\Service\Wopi\UserManager;

return static function (ContainerConfigurator $container) {
    $services = $container
        ->services();

    $services
        ->defaults()
        ->autowire()
        ->autoconfigure();

    $services
        ->set(ChillDocumentManager::class);

    $services
        ->alias(DocumentManagerInterface::class, ChillDocumentManager::class);

    $services
        ->set(AuthorizationManager::class);

    $services->alias(AuthorizationManagerInterface::class, AuthorizationManager::class);

    $services
        ->set(UserManager::class);

    $services->alias(UserManagerInterface::class, UserManager::class);
};

Create an editor page

The editor page will be the page which will load the editor, through an iframe.

Here is a controller:

<?php

declare(strict_types=1);

namespace App\Controller;

use ChampsLibres\WopiLib\Contract\Service\Configuration\ConfigurationInterface;
use ChampsLibres\WopiLib\Contract\Service\Discovery\DiscoveryInterface;
use ChampsLibres\WopiLib\Contract\Service\DocumentManagerInterface;
use Chill\DocStoreBundle\Entity\StoredObject;
use Chill\MainBundle\Entity\User;
use Chill\WopiBundle\Service\Controller\ResponderInterface;
use Exception;
use Lexik\Bundle\JWTAuthenticationBundle\Services\JWTTokenManagerInterface;
use loophp\psr17\Psr17Interface;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Routing\RouterInterface;
use Symfony\Component\Security\Core\Security;

final class Editor
{
    private DocumentManagerInterface $documentManager;

    private JWTTokenManagerInterface $JWTTokenManager;

    private Psr17Interface $psr17;

    private ResponderInterface $responder;

    private RouterInterface $router;

    private Security $security;

    private ConfigurationInterface $wopiConfiguration;

    private DiscoveryInterface $wopiDiscovery;

    public function __construct(
        ConfigurationInterface $wopiConfiguration,
        DiscoveryInterface $wopiDiscovery,
        DocumentManagerInterface $documentManager,
        JWTTokenManagerInterface $JWTTokenManager,
        ResponderInterface $responder,
        Security $security,
        Psr17Interface $psr17,
        RouterInterface $router
    ) {
        $this->documentManager = $documentManager;
        $this->JWTTokenManager = $JWTTokenManager;
        $this->wopiConfiguration = $wopiConfiguration;
        $this->wopiDiscovery = $wopiDiscovery;
        $this->responder = $responder;
        $this->security = $security;
        $this->psr17 = $psr17;
        $this->router = $router;
    }

    public function __invoke(string $fileId): Response
    {
        if (null === $user = $this->security->getUser()) {
            throw new AccessDeniedHttpException('Please authenticate to access this feature');
        }

        $configuration = $this->wopiConfiguration->jsonSerialize();
        $storedObject = $this->documentManager->findByDocumentId($fileId);

        if (null === $storedObject) {
            throw new NotFoundHttpException(sprintf('Unable to find object %s', $fileId));
        }

        if ([] === $discoverExtension = $this->wopiDiscovery->discoverMimeType($storedObject->getType())) {
            throw new Exception(sprintf('Unable to find mime type %s', $storedObject->getType()));
        }

        $configuration['favIconUrl'] = '';
        $configuration['access_token'] = $this->JWTTokenManager->createFromPayload($user, [
            'UserCanWrite' => true,
            'UserCanAttend' => true,
            'UserCanPresent' => true,
            'fileId' => $fileId,
        ]);

        // we parse the jwt to get the access_token_ttl
        // reminder: access_token_ttl is a javascript epoch, not a number of seconds; it is the
        // time when the token will expire, not the time to live:
        // https://learn.microsoft.com/en-us/microsoft-365/cloud-storage-partner-program/rest/concepts#the-access_token_ttl-property
        $jwt = $this->JWTTokenManager->parse($configuration['access_token']);
        $configuration['access_token_ttl'] = $jwt['exp'] * 1000;

        $configuration['server'] = $this
            ->psr17
            ->createUri($discoverExtension[0]['urlsrc'])
            ->withQuery(
                http_build_query(
                    [
                        'WOPISrc' => $this
                            ->router
                            ->generate(
                                'checkFileInfo',
                                [
                                    'fileId' => $this->documentManager->getDocumentId($storedObject),
                                ],
                                UrlGeneratorInterface::ABSOLUTE_URL
                            ),
                        'closebutton' => 1,
                    ]
                )
            );

        return $this
            ->responder
            ->render(
                '@Wopi/Editor/page.html.twig',
                $configuration
            );
    }
}

Troubleshooting

check your collabora / CODE 's logs. They provide information about error from within WOPI calls;
use the profiler to debug the call to WOPI endpoint made behind the scene by the wopi client.

Documentation

https://wopi.readthedocs.io/en/latest/

Code quality, tests, benchmarks

Every time changes are introduced into the library, Github runs the tests.

The library has tests written with PHPUNIT.

Before each commit, some inspections are executed with GrumPHP; run composer grumphp to check manually.

The quality of the tests is tested with Infection a PHP Mutation testing framework, run composer infection to try it.

Static analyzers are also controlling the code. PHPStan and PSalm are enabled to their maximum level.

Contributing

Feel free to contribute to this project by submitting pull requests on Github.

Changelog

See CHANGELOG.md for a changelog based on git commits.

For more detailed changelogs, please check the release changelogs.

champs-libres / wopi-bundle

Maintainers

Details