ActivityPub Application

Last modified by Thomas Mortagne on 2024/07/05 17:55

A social application to allow XWiki to be part of the fediverse

Type	XAR
Category	Application
Developed by	Simon Urli, Manuel Leduc
Active Installs	0
Rating	1 2 3 4 5 0 Votes
License	GNU Lesser General Public License 2.1

Compatibility

XWiki Standard 12.10+

Installable with the Extension Manager

Download v1.7.11SourcesIssues

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.

Presentation

Here's a video of a presentation of this extension at ActivityPubConf 2020.

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

XWiki <1.5

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.

XWiki 1.5+ The messages are now part of the discussions described below.

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.

XWiki 1.4+

Mentioning an ActivityPub Actor

Mentioning an ActivityPub is based on the mention mechanism provided by Mentions Application.
XWiki 12.10 allows to mention various kind of users, but the feature is not yet integrated in the user interface.
To mention an ActivityPub user, a mention macro should be integrated in the document sources following the sample below:

{{mention reference="[email protected]" style="FULL_NAME" anchor="uniqueAnchor" type="activitypub"/}}

Currently, mentioning a Mastodon user send an activity to the Mastodon instance of the user, but Mastodon does not accept mentions on Page entities.

Like elements

XWiki 1.4+ It is possible to directly like ActivityPub elements from the Notification area by clicking on the heart icon next to them in the detailed view.
All the elements that have been liked can be found in the dedicated view in ActivityPub main dashboard.

XWiki 1.5+

It's possible to see how many people liked a page from the fediverse, directly on the like counter, and also to see who are the people who liked a page from the fediverse, by going in the "other actions" menu.

It's also possible to enable notifications for Like performed through the fediverse, for an XWiki user to know when some of her actions have been liked from the fediverse.

Discussions

XWiki 1.5+

The discussions presents the Note object exchanged between ActivityPub instance in a structured way.
The discussions can be created, listed and viewed from the ActivitPub application.
Notes received from the Fediverse are also handled. A Note is either integrated to the discussions if it is a reply to an existing Note, otherwise a new discussions is created.

Create a discussion

Using the New Message tab of the dashboard, the user can send a message to a list of users.
One the message is sent, a discussion containing this message is automatically created.
This new discussion is visible in the list of discussions.

List the Discussions

The dashboard provides a Discussion tab displaying the discussions related to the current actor.

{{/gallery}

Reply from the notifications

It is possible to contribute to a discussion from the notification pane by using the reply button.
Clicking on the reply button open a modal screen with a form, allowing to add a message to the discussion of the activity linked to the notification.
If the discussion does not exist, it is created when a first message is sent.

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)
Like (of ActivityPub activities) (since 1.4)

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 / Like
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/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:

Log in the wiki with a user having Administration rights
Go to the Administration page and select the Import category
Follow the on-screen instructions to upload the downloaded XAR
Click on the uploaded XAR and follow the instructions
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.