Update setup and integration docs
This commit is contained in:
JC Brand
parent
f908463ab9
commit
8d0cf8fa8c
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user