Spar manual updates (#256)

* Cross-reference topics.

* Inline SAML/SSO design.rst.

* Concepts.

* Further reading.

src/index.rst

@@ -22,7 +22,6 @@ This documentation may be expanded in the future to cover other aspects of Wire.
    Administrator's Guide <how-to/index.rst>
    Understanding wire-server components <understand/index.rst>
    Single-sign-on how-tos <how-to/single-sign-on/index.rst>
-   Single-sign-on background (fragment) <understand/single-sign-on/design.rst>
    Administrator's manual: single-sign-on and user provisioning <understand/single-sign-on/main.rst>
    How to set up user provisioning with LDAP or SCIM <how-to/scim/index.rst>
    Client API documentation <understand/api-client-perspective/index.rst>

src/understand/single-sign-on/design.rst

@@ -1,19 +1 @@
-Single-sign-on background and design choices (fragment)
-=======================================================
-
-Overview
---------
-
-Here is a blog post we like about how SAML works: https://duo.com/blog/the-beer-drinkers-guide-to-saml
-
-And here is a diagram that explains it in slightly more technical terms:
-
-.. image:: Wire_SAML_Flow.png
-
-
-See also
---------
-
-:ref:`Trouble shooting & FAQ <trouble-shooting-faq>`
-
-A critique of XML security, and why you should use oauth instead: https://www.cs.auckland.ac.nz/~pgut001/pubs/xmlsec.txt
+This page is gone.  Please visit `this one <./main.html>`_

src/understand/single-sign-on/main.rst

@@ -34,6 +34,20 @@ This page explains how to set up :term:`SCIM` and then use it.
     See below in the :term:`SCIM` section for a more detailled explanation.
 
 
+Futher reading
+~~~~~~~~~~~~~~
+
+If you can't find the answers to your questions here, we have a few
+more documents.  Some of them are very technical, some may not be up
+to date any more, and we are planning to move many of them into this
+page.  But for now they may be worth checking out.
+
+- :ref:`Trouble shooting & FAQ <trouble-shooting-faq>`
+- https://support.wire.com/hc/en-us/sections/360000580658-Authentication
+- https://github.com/wireapp/wire-server/blob/1753b790e5cfb2d35e857648c88bcad3ac329f01/docs/reference/spar-braindump.md
+- https://github.com/wireapp/wire-server/tree/1753b790e5cfb2d35e857648c88bcad3ac329f01/docs/reference/provisioning/
+
+
 Definitions
 ~~~~~~~~~~~
 
@@ -130,8 +144,18 @@ Introduction
 
 SSO (Single Sign-On) is technology allowing users to sign into multiple services with a single identity provider/credential.
 
+SSO is about `authentication`, not `provisioning` (create, update, remove user accounts).  To learn more about the latter, continue  `below <main.html#user-provisioning-scim-ldap>`_.
+
 For example, if a company already has SSO setup for some of their services, and they start using Wire, they can use Wire's SSO support to add Wire to the set of services their users will be able to sign into with their existing SSO credentials.
 
+Here is a blog post we like about how SAML works: https://duo.com/blog/the-beer-drinkers-guide-to-saml
+
+And here is a diagram that explains it in slightly more technical terms:
+
+.. image:: Wire_SAML_Flow.png
+
+Here is a critique of XML/DSig security (which SAML relies on): https://www.cs.auckland.ac.nz/~pgut001/pubs/xmlsec.txt
+
 Terminology and concepts
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -142,10 +166,7 @@ Terminology and concepts
 * Identity Provider (IdP): Defines the entity that provides the user identities, including the ability to authenticate a user to get access to a protected resource / application from a Service Provider. To accomplish
   the SAML based SSO authentication, the IdP must have the Service Provider's metadata.
 * SAML Request: This is the authentication request generated by the Service Provider to request an authentication from the Identity Provider for verifying the user's identity.
-* SAML Response: The SAML Response contains the actual assertion of the authenticated user and is generated by the Identity Provider. The SAML Response also consists of additional information such as user profile
-  information, group or role information and so on based on what the Service Provider can support.
-* Service Provider-initiated Authentication Flow: This describes the SAML authentication flow initiated by the Service Provider. The authentication process from the SP is triggered when the user tries to access a
-  resouce or log on to the Service Provider application. A typical example is that of a browser trying to access a protected resource from the Service Provider.
+* SAML Response: The SAML Response contains the cryptographically signed assertion of the authenticated user and is generated by the Identity Provider.
 
 (Definitons adapted from `collab.net <http://help.collab.net/index.jsp?topic=/teamforge178/action/saml.html>`_)
 
@@ -197,8 +218,10 @@ If you haven't set up :term:`SCIM` (`we recommend you do <#introduction>`_), you
 
 If team members already have Wire accounts, use :term:`SCIM` to associate them with the :term:`SAML` credentials.  If you make a mistake here, you may end up with several accounts for the same person.
 
-SCIM user provisioning
-~~~~~~~~~~~~~~~~~~~~~~
+User provisioning (SCIM/LDAP)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+SCIM/LDAP is about `provisioning` (create, update, remove user accounts), not `authentication`.  To learn more about the latter, continue `above <main.html#saml-sso>`_.
 
 SCIM management in Wire (in Team Management)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^