From 8d0cf8fa8c789339b4ddfb3f24df19eec9c478b2 Mon Sep 17 00:00:00 2001 From: JC Brand Date: Wed, 13 Sep 2017 11:12:15 +0200 Subject: [PATCH] Update setup and integration docs --- docs/source/setup.rst | 154 +++++++++++++++++++++++++++--------------- 1 file changed, 99 insertions(+), 55 deletions(-) diff --git a/docs/source/setup.rst b/docs/source/setup.rst index 067258ca4..de89205de 100644 --- a/docs/source/setup.rst +++ b/docs/source/setup.rst @@ -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 `_). + This diagram shows the various services in a fairly common setup (image generated with `draw.io `_). +---------------------- +The various components +---------------------- .. _`XMPP server`: @@ -59,19 +63,23 @@ have :ref:`session support ` you'll have to set up your own XMP You can find a list of public XMPP servers/providers on `xmpp.net `_ and a list of servers that you can set up yourself on `xmpp.org `_. -.. _`BOSH connection manager`: +.. _`BOSH-section`: -A BOSH Connection Manager -========================= +BOSH +==== -Your website and *Converse.js* use `HTTP `_ -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 `_, prosody `(mod_bosh) `_ and `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 `_ (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 `_ @@ -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 `_ @@ -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 `_ 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 `_. 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