cogA social application to allow XWiki to be part of the fediverse
TypeXAR
CategoryApplication
Developed by

Simon Urli, Manuel Leduc

Active Installs1
Rating
Rate!
0 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager

Description

The ActivityPub application aims at allowing to connect XWiki with other instances of the fediverse.

Quick Overview

Once installed the ActivityPub Application allows an XWiki instance to be part of the fediverse: all users of this instance are reachable for other ActivityPub services, or other XWiki instances using the same extension. 

Users of an XWiki instance can interact with ActivityPub in two main places:
  - the ActivityPub links, in the application menu
  - or the ActivityPub tab in any users' profile

Note that those places can also be used by guest users of the wiki, to retrieve the identifier of an user, to use it in another service.
The application might also insert new buttons and actions in pages, like the Share page button.
For administrators, a new ActivityPub page is available in Administration.

Available activities

ActivityPub focused on sharing activities between several instances of the fediverse.

Follow User

Following an XWiki user allows to receive Create and Update notifications when this user authored a change in the wiki.

To follow an user in XWiki, go in the ActivityPub application you will get a form that allows you to enter the identifier of a user to follow him/her.
Note that this identifier is needed for all kind of ActivityPub interaction, if it is about an XWiki user from another instance, you can find the identifier in his profile, in the "ActivityPub" pane. 

Messaging

Any user can send messages to her followers, or to any other ActivityPub user.
For sending a message, go in the ActivityPub application and click on the "Messaging" tab. You will be asked to enter the targeted users by giving their identifiers, but you can also choose your followers.

Two tabs are available in the dashboard since ActivityPub 1.2 if you want to consult the received or sent messages.

Sharing documents

XWiki users can share documents to other ActivityPub users (both local and remote).
For sharing a document, go to any wiki page and click on the share button at the top right of the page (see the gallery below). You will be asked to enter the targeted users, but you can also choose your followers.

Documents are also shared automatically to your followers when you create or update public documents of a wiki.

The content of shared documents is sent to the receivers. That way, receivers of shared documents can consult them in place on modal popups.

Public Target

Note that you can select "public" in some activities such as Messaging or Sharing documents: this makes explicit the fact that this activity is public and can be retrieved by anyone without needing any credentials. So this target should be used carefully for respecting privacy.

Wiki Actor

Starting with ActivityPub 1.2, an entire Wiki of XWiki can act as a specific ActivityPub Actor. This means that anyone is able to follow an entire Wiki, or to sent message to it, etc. Following a Wiki will allow to receive ActivityPub events for any document created or updated on that wiki. It is also possible for the people who administrate the Wiki to use it as an ActivityPub actor to send messages or follow other people.

To follow a Wiki just go to the ActivityPub Dashboard as a guest user, and you will get the identifier to use for following that wiki. To manage the Wiki actor, if you are entitled to do so, once you are logged-in on your Wiki you should be able to switch roles in the ActivityPub dashboard.

Some options are available in the Administration for managing the Wiki actor: you can chose which XWiki Group is entitled to manage the ActivityPub Wiki Actor. By default, the Admin group is selected, but you can use any group. Any people belonging to that group will be able to perform actions on behalf of the Wiki on ActivityPub, such as receiving the notifications for the Wiki, following people/other Wiki, send messages etc.

View remote content

Starting with ActivityPub 1.2, a remote content shared on the fediverse can be seen directly on XWiki.
When an ActivityPub notification concerns a document, a button is now available to display its content directly without having to go outside the wiki.

Supported Fediverse instances

 

Our first usecase for creating this extension is to connect XWiki with another instance of XWiki, but of course, other kinds of applications using ActivityPub should also be able to interact with it. However, depending on the implementation and on the maturity of the projects, it's not always as true as we would want to emoticon_smile.
We try to list here the application which implements ActivityPub and the status of the interaction with our own extension.

We currently progress toward a support of Nextcloud and Mastodon. While we tests mainly those two ActivityPub services, other services supporting the ActivityPub protocol might support social interactions with XWiki.
We support:

  • Following users.
  • The transmission of messages from Mastodon and Nextcloud to XWiki instances.

Don't hesitate to provide your own feedback!

Administration

 

We list here the available options to administrate the application.

Follow Policy

It is possible to decide what policy to adopt globally for the follow request received on this instance, for any user of the instance.
Two options are available:

  • Accept (default value): the requests are automatically accepted
  • Reject: all follow requests are automatically rejected.

Group that manage the current wiki

Use that section to decide which group is entitled to act on behalf of the Wiki actor.

Page Notifications

Use those settings to change the behaviour of the ActivityPub Events triggered when a page is created or modified.

  • Enable Page notifications: if disabled no events will be ever sent in case of document creation or update.
  • Page Notification Policy: two options are available:
    • Whole Wiki + Author: the events will be send for both the Wiki's followers and the author's followers
    • Whole Wiki: the events will be sent only to the Wiki's followers

Endpoints

We provide here some information for developers who wants to interact directly with the provided endpoints. 

ActivityPub

URL scheme

The URL scheme to interact with ActivityPub on XWiki is the following:

http://{serverUrl}/xwiki/activitypub/{entityType}/{entityId}

with entityType being an entity defined in ActivityStream vocabulary or in ActivityPub (e.g. some extensions like Outbox and Inbox) and entityId an identifier returned by the application.

All requests should be submitted with the right headers as explained below.

Even if the context path of the URL can be customized in XWiki, the ActivityPub extension doesn't support it for now, you should keep using /xwiki/ if you want it to work properly.

GET Requests

As specified in the ActivityPub draft, all GET request must be performed with an Accept header with the following value:
application/ld+json; profile="https://www.w3.org/ns/activitystreams"

A GET request can be performed on any resource of ActivityPub as soon as they are recorded in the store. The only exception is for actors which are created on the fly to synchronize them with XWiki users.

So a good first start to perform an ActivityPub request is to ask for a user: 

http://serverUrl/xwiki/activitypub/person/XWiki.username

POST Requests

All POST request must be performed with a Content-Type header with the following value:
application/ld+json; profile="https://www.w3.org/ns/activitystreams"

POST requests are only authorized on Inbox and Outbox of users: to retrieve the right endpoints for those, use a GET request on actors (see above).
POST on an Outbox must necessarily be authenticated by the user of the Outbox. We use for now the same mechanism as for XWiki REST request authentication.
The body of the POST request must be necessarily an Activity.

The ActivityPub draft informs that in case of POST of an object, it should be wrapped into a Create activity: this should be implemented in the future.

Activities

Here's the list of currently supported activities:

  • Create (of documents or pages)
  • Follow (of user only and wikis)
  • Accept (of follow only)
  • Reject (of follow only)
  • Update (of documents or pages)
  • Announce (of documents or pages)

Note that the federation is not well supported yet: only the followers on Create activity are informed about actions. The to and cc attribute are not handled yet.

Full list of ActivityPub/ActivityStream supported entities

Here's the list of all supported entities for GET requests (they are grouped by type):

  • actor / person / service
  • outbox / inbox
  • orderedcollection / collection
  • accept / create / reject / follow / announce
  • note / document / page

Security

ActivityPub defines some mechanisms to address the security of the protocol.
HTTP Signatures allows the authentication of an actor interacting with a remote Inbox.
JSON-LD Signatures allows the authentication of the actor emitting a JSON-LD Object. This is for instance used to check the author of a message.

Currently we sign outgoing messages with HTTP Signatures and we do not verify incoming messages' signature.
Support of JSON-LD Signatures will be implemented in the next releases.

Webfinger

WebFinger is a draft protocol that allows requesting users' information on a dedicated domain. It is not a part of the original ActivityPub draft protocol, but we included it in this application since it is really helpful to resolve users' identifiers. 

URL Scheme

The XWiki scheme URL to resolve WebFinger request is:
http://serverUrl/xwiki/webfinger/?resource={actorId}@{domain}

Note that this scheme is not the actual URL scheme asked by the protocol, which is why you need to configure properly your server to resolve the following scheme URL:

http://{domain}/.well-known/webfinger?resource={actorId}@{domain}

Where domain is the public domain of you server, and actorId is the qualified username of the user.

Links

 

ActivityPub draft protocol
Webfinger draft protocol

Acknowledgements

The development of this extension has been partly funded by NLnet fundation as part of the NGI Search & Discovery call.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Webfinger Installation

This step is optional but heavily recommended since it will allow your user to have the best experience with ActivityPub.

Webfinger is a protocol that allows discovering users' information automatically. An implementation is provided with ActivityPub Application, but the protocol requires that the requests are made on a specific endpoint. Webfinger specifications require the /.well-known/webfinger endpoint to be placed at the root of the server to be discoverable.

The configuration of the reverse-proxy must be configured accordingly.
The example below shows how to adapt the Nginx configuration of XWiki for Webfinger.

The block below must be added before the location / { ... } block of the Nginx configuration.

location ~* ^/.well-known/webfinger(.*)$ {
  access_log off;
  rewrite ^/.well-known/webfinger(.*) /xwiki/webfinger$1 permanent;
  expires 0m;
}

ActivityPub Notifications

ActivityPub Application relies a lot on XWiki Notifications, so don't forget to enable the notifications for ActivityPub after installing it.

Release Notes

v1.3

Release Notes for ActivityPub Application 1.3

v1.2.1

Release Notes for ActivityPub Application 1.2.1

v1.2

Release Notes for ActivityPub Application 1.2

v1.1

Release Notes for ActivityPub Application 1.1

Dependencies

Dependencies for this extension (org.xwiki.contrib:activitypub-ui 1.3):

Tags:
Created by Simon Urli on 2020/03/02 16:28
    

Get Connected