Update setup and integration docs

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 <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`:
+
+BOSH
+====
+
+Web-browsers do not allow the persistent, direct TCP socket connections used by
+desktop XMPP clients to communicate with XMPP servers.
 
-A BOSH Connection Manager
-=========================
+Instead, we have HTTP and websocket as available protocols.
 
-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.
+`BOSH`_ can be seen as XMPP-over-HTTP. In other words, it allows for XMPP
+stanzas to be sent over an HTTP connection.
 
-XMPP on the other hand, is the protocol that enables instant messaging, and
-its connections are stateful and usually last much longer.
+HTTP connections are stateless and usually shortlived.
+XMPP connections on the other hand are stateful and usually last much longer.
 
-To enable a web application like *Converse.js* to communicate with an XMPP
+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.
+
+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 3). Cryptographically signed tokens
-==========================================
+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