Chapril/xmpp.chapril.org-conversejs
Chapril/xmpp.chapril.org-conversejs
25
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

Merge remote-tracking branch 'origin/master'

Browse Source
This commit is contained in:
Weblate 2017-09-13 11:12:35 +02:00
commit 7cdb0df4e9
1 changed files with 99 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
docs/source/setup.rst
View File

@ -8,41 +8,45 @@ Setup and integration
.. _what-you-will-need:
------------------
What you will need
------------------
This page documents what you'll need to do to be able to connect Converse.js with
your own XMPP server and to better integrate it into your website.
If you'd like to host your own version of Converse.js or you would like to
integrate it into your website, then you'll need to do some further setup work.
At the very least you'll need Converse.js and an :ref:`XMPP server` with
:ref:`websocket-section` or :ref:`BOSH-section` enabled. That's definitely
enough to simply demo Converse.js or to do development work on it.
For example, if you want to allow chat accounts under your own domain (i.e.
the same domain as your website), then you will need to set up your
own :ref:`XMPP server` that hosts accounts under that domain.
However, if you want to more fully integrate it into a website or intranet,
then you'll likely need to set up more services and components.
Besides an XMPP server, you'll also need a way for Converse.js (which uses HTTP
or Websocket), to communicate with the XMPP server(s).
The diagram below shows a fairly common setup for a website or intranet:
Here you have two choices. You can either use a :ref:`BOSH Connection Manager`
(standalone or integrated into the XMPP server) which allows you to use the
XMPP protocol over HTTP, or you can use a websocket connection if your XMPP
server supports it.
* Converse.js runs in the web-browser on the user's device.
Furthermore, it's possible to let users who are authenticated against your web
application to also automatically be logged in to the XMPP server.
* It communicates with the XMPP server via BOSH or websocket which is usually
reverse-proxied by a web-server in order to overcome cross-site scripting
restrictions in the browser. For more info on that, read the section:
`Overcoming cross-domain request restrictions`_
There are various ways in which this can be achived. One way of doing this is
to use a directory service such as LDAP or Active Directory and to share it
between your backend web application and your XMPP server. The diagram below
assumes such a setup.
* Optionally the XMPP server is configured to use a SQL database for storing
archived chat messages.
For other options, please read the section: :ref:`session-support`.
* Optionally there is a user directory such as Active Directory or LDAP, which
the XMPP server is configured to use, so that users can log in with those
credentials.
* Usually (but optionally) there is a backend web application which hosts a
website in which Converse.js appears.
.. figure:: images/diagram.png
:align: center
:alt: A diagram of a possible setup, consisting of Converse.js, a web server, a backend web application, an XMPP server, a user directory such as LDAP and an XMPP server.
This diagram shows a potential setup containing various services (image generated with `draw.io <https://draw.io>`_).
This diagram shows the various services in a fairly common setup (image generated with `draw.io <https://draw.io>`_).
----------------------
The various components
----------------------
.. _`XMPP server`:
@ -59,19 +63,23 @@ have :ref:`session support <session-support>` you'll have to set up your own XMP
You can find a list of public XMPP servers/providers on `xmpp.net <https://list.jabber.at>`_
and a list of servers that you can set up yourself on `xmpp.org <http://xmpp.org/xmpp-software/servers/>`_.
.. _`BOSH connection manager`:
.. _`BOSH-section`:
A BOSH Connection Manager
=========================
BOSH
====
Your website and *Converse.js* use `HTTP <https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol>`_
as protocol to communicate with the webserver. HTTP connections are
stateless and usually shortlived.
Web-browsers do not allow the persistent, direct TCP socket connections used by
desktop XMPP clients to communicate with XMPP servers.
XMPP on the other hand, is the protocol that enables instant messaging, and
its connections are stateful and usually last much longer.
Instead, we have HTTP and websocket as available protocols.
To enable a web application like *Converse.js* to communicate with an XMPP
`BOSH`_ can be seen as XMPP-over-HTTP. In other words, it allows for XMPP
stanzas to be sent over an HTTP connection.
HTTP connections are stateless and usually shortlived.
XMPP connections on the other hand are stateful and usually last much longer.
So to enable a web application like *Converse.js* to communicate with an XMPP
server, we need a proxy which acts as a bridge between these two protocols.
This is the job of a BOSH connection manager. BOSH (Bidirectional-streams Over
@ -81,7 +89,7 @@ protocol is defined in `XEP-0206: XMPP Over BOSH <http://xmpp.org/extensions/xep
Popular XMPP servers such as `Ejabberd <http://www.ejabberd.im>`_,
prosody `(mod_bosh) <http://prosody.im/doc/setting_up_bosh>`_ and
`OpenFire <http://www.igniterealtime.org/projects/openfire/>`_ all include
their own connection managers (but you usually have to enable them in the
their own BOSH connection managers (but you usually have to enable them in the
configuration).
However, if you intend to support multiple different servers (like
@ -96,8 +104,13 @@ manager located at https://conversejs.org/http-bind.
This connection manager is available for testing purposes only, please don't
use it in production.
Alternatively, Websocket support
================================
Refer to the :ref:`bosh-service-url` configuration setting for information on
how to configure Converse.js to connect to a BOSH URL.
.. _`websocket-section`:
Websocket
=========
Websockets provide an alternative means of connection to an XMPP server from
your browser.
@ -108,16 +121,22 @@ HTTP. Therefore BOSH, which operates over HTTP, doesn't apply to websockets.
`Prosody <http://prosody.im>`_ (from version 0.10) supports websocket connections, as
does the node-xmpp-bosh connection manager.
--------------------------------------------
Refer to the :ref:`websocket-url` configuration setting for information on how to
configure Converse.js to connect to a websocket URL.
The Webserver
=============
Overcoming cross-domain request restrictions
--------------------------------------------
Lets say your domain is *example.org*, but the domain of your connection
manager is *example.com*.
HTTP requests are made by *Converse.js* to the connection manager via XmlHttpRequests (XHR).
Until recently, it was not possible to make such requests to a different domain
than the one currently being served (to prevent XSS attacks).
HTTP requests are made by *Converse.js* to the BOSH connection manager via
XmlHttpRequests (XHR). Until recently, it was not possible to make such
requests to a different domain than the one currently being served
(to prevent XSS attacks).
Luckily there is now a standard called
`CORS <https://en.wikipedia.org/wiki/Cross-origin_resource_sharing>`_
@ -134,8 +153,8 @@ Instead of using CORS, you can add a reverse proxy in
Apache/Nginx which serves the connection manager under the same domain as your
website. This will remove the need for any cross-domain XHR support.
For example:
============
Examples:
*********
Assuming your site is accessible on port ``80`` for the domain ``mysite.com``
and your connection manager manager is running at ``someothersite.com/http-bind``.
@ -147,7 +166,7 @@ the cross-domain restriction is ``mysite.com/http-bind`` and not
Your ``nginx`` or ``apache`` configuration will look as follows:
Nginx
-----
~~~~~
.. code-block:: nginx
@ -162,7 +181,7 @@ Nginx
}
Apache
------
~~~~~~
.. code-block:: apache
@ -175,9 +194,8 @@ Apache
.. _`session-support`:
----------------------
Single Session Support
----------------------
======================
It's possible to enable shared sessions whereby users already
logged in to your website will also automatically be logged in on the XMPP server,
@ -190,7 +208,7 @@ XMPP server once they've logged in to your site.
Option 1). Server-side authentication via BOSH prebinding
=========================================================
---------------------------------------------------------
To **prebind** refers to a technique whereby your web application sets up an
authenticated BOSH session with the XMPP server or a standalone `BOSH <http://xmpp.org/about-xmpp/technology-overview/bosh/>`_
@ -260,7 +278,7 @@ Please read the documentation on those settings for a fuller picture of what
needs to be done.
Example code for server-side prebinding
---------------------------------------
***************************************
* PHP:
See `xmpp-prebind-php <https://github.com/candy-chat/xmpp-prebind-php>`_ by
@ -271,18 +289,44 @@ Example code for server-side prebinding
Option 2). Delegated authentication, also called external authentication
========================================================================
------------------------------------------------------------------------
An alternative to BOSH prebinding is to generate temporary authentication
tokens which are then sent to the XMPP server and which it in turn checks
against some kind of external authentication provider (generally the same web-app that
generated the tokens).
Delegated authentication refers to the usecase where the XMPP server delegates
authentication to some other service.
In this case, you could use the :ref:`credentials_url` setting, to specify a
URL from which converse.js should fetch the username and token.
This could be to LDAP or Active Directory (as shown in the diagram at the top
of the page), or it could be to an OAuth provider, a SQL server to a specific
website.
Option 3). Cryptographically signed tokens
==========================================
The Prosody webserver has various user-contributed modules which delegate
authentication to external services. They are listed in the `Prosody community modules
page <https://modules.prosody.im/>`_. Other XMPP servers have similar plugin modules.
If your web-application has access to the same credentials, it can send those
credentials to Converse.js so that user's are automatically logged in when the
page loads.
This is can be done by setting `auto_login`_ to true and configuring the
the `credentials_url`_ setting.
Option 3). Temporary authentication tokens
------------------------------------------
The first option has the drawback that your web-application needs to know the
XMPP credentials of your users and that they need to be stored in the clear.
The second option has that same drawback and it also needs to pass those
credentials to Converse.js.
To avoid these drawbacks, you can instead let your backend web application
generate temporary authentication tokens which are then sent to the XMPP server
which in turn delegates authentication to an external authentication provider
(generally the same web-app that generated the tokens).
This can be combined with prebind or with the :ref:`credentials_url` setting.
Option 4). Cryptographically signed tokens
------------------------------------------
A third potential option is to generate cryptographically signed tokens (e.g.
HMAC tokens) which the XMPP server could authenticate by checking that they're