Easy Onboarding: use cases

inbox/user-invite.xml

@@ -170,10 +170,67 @@
     description and the <strong>expire</strong> information, so that Romeo can
     share it with Juliet by other means than XMPP, like e-mail or a QR code.</p>
   </section2>
-  <section2 topic='Redeeming a User Invitation' anchor='redeem-invitation'>
-    <p></p>
+  <section2 topic='Landing Page' anchor='landing-page'>
+    <p>The landing page that the generated URL points to should correspond to
+      the format described in <cite>XEP-0379</cite> §3.3, and it needs to
+      convey the following information:</p>
+    <ul>
+      <li>A short text that this is an XMPP invitation from Romeo.</li>
+      <li>A client recommendation (based on the detected web browser/OS) with download links.</li>
+      <li>A prominent button that activates the encoded <strong>xmpp:</strong> link.</li>
+    </ul>
+    <p>If the landing page is hosted by Romeo's server, the server MAY display
+      additional information based on the supplied TOKEN value, like the name
+      of the inviter or validity information.</p>
   </section2>
-  <section2 topic='Account Creation' anchor='account-creation'>
+  <section2 topic='Redeeming a User Invitation' anchor='redeem-invitation'>
+    <p>If Juliet does not have an XMPP client installed, she will not be able
+      to open the <strong>xmpp:</strong> link from the invitation page.
+      For this case, the landing page needs to indicate that a client must be
+      installed first, and that the link will not work as intended without.
+      The automatic installation of an appropriate IM client when a user
+      clicks on an <strong>xmpp:</strong> is outside of the scope of this
+      document.</p>
+    <p>With an XMPP client installed, Juliet can open the
+      <strong>xmpp:</strong> link and have the client process it
+      appropriately, as follows:</p>
+    <section3 topic='Pre-Configured Account' anchor='redeem-preconfigured'>
+      <p>If Juliet's client is already configured with an account, the default
+	action for the presented
+	<strong>xmpp:inviter@example.com?roster;...</strong> URI is to add the
+	inviter to Juliet's roster. This should be performed as described in
+	§3.4 of <cite>XEP-0379</cite>, by sending a presence subscription
+	request containing the 'preauth' token.</p>
+      <p>If Juliet already has Romeo in her roster, her client should open the
+	appropriate chat interface instead.</p>
+    </section3>
+    <section3 topic='No Configured Account' anchor='redeem-no-account'>
+      <p>If Juliet's client does not have an XMPP account configured, she
+	needs to login or register an account first. Therefore, the client
+	should provide an interface with the following options:</p>
+      <ul>
+	<li>Login with an existing XMPP account.</li>
+	<li>Register an account with Romeo's server (if the URI contains a
+	  <strong>ibr=y</strong> parameter).</li>
+	<li>Register an account with a public or client-endorsed server.</li>
+      </ul>
+      <p>If the <strong>xmpp:</strong> URI provided by Romeo contains the
+	<strong>ibr=y</strong> parameter, it indicates that the server
+	supports the <link url="#preauth-ibr">Pre-Authenticated In-Band
+	Registration</link> defined in this document. If Juliet chooses this
+	approach, the server will ensure that after the registration, Romeo is
+	added to her roster with a full presence subscription.</p> <p>If
+	Juliet chooses to login or register with a different server, her
+	client must complete the respective process and issue a subscription
+	request as described in §3.4 of <cite>XEP-0379</cite>.</p>
+    </section3>
+    </section2>
+  <section2 topic='Initiating Account Creation' anchor='account-creation'>
+    <p>If Romeo is the administrator of an XMPP server, he might want to
+      ensure that Juliet obtains an account on this server, with a username
+      defined either by Romeo or by Juliet, and in a way that does not require
+      the out-of-band communication of user passwords.</p>
+    <p>TODO: description of overall process steps, design motivation.</p>
     <example caption="Exceute account creation command"><![CDATA[
 <iq type='set' from='romeo@example.com' to='example.com' id='exec1'>
   <command xmlns='http://jabber.org/protocol/commands'
@@ -244,12 +301,14 @@
       local part of the JID in the XMPP URI is omitted by the server which
       results in the following format:</p>
     <code>xmpp:example.com?register;preauth=TOKEN</code>
+    <p>TODO: note about sensitivity of TOKEN</p>
   </section2>
-  <section2 topic='Extension of In-Band Registration'>
-    <p>In order to allow invited users to register on a server, in-band
-      registration as defined in &xep0077; needs to be extended.
-      The invited user MUST send the following extended stanza in order to
-      register an account with a token.</p>
+  <section2 topic='Pre-Authenticated In-Band Registration' anchor='preauth-ibr'>
+    <p>In order to allow invited users to register on a server, the
+      registration processs as defined in &xep0077; needs to be extended. The
+      invited user's client MUST add a &lt;preauth&gt; element in the 'TODO'
+      namespace to the 'jabber:iq:register' query in order to inform the
+      server that it wants to perform Pre-Authenticated IBR:</p>
     <example caption="Retrieving registration fields"><![CDATA[
 <iq type='get' id='reg1' to='example.com'>
   <query xmlns='jabber:iq:register'>
@@ -257,6 +316,9 @@
   </query>
 </iq>
 ]]></example>
+    <p>If the server supports and is ready to perform Pre-Authenticated IBR,
+      it MUST add a &lt;token&gt; element to the response (TODO: 'token' or
+      'preauth'?):</p>
     <example caption="Receiving registration fields"><![CDATA[
 <iq type='result' to='romeo@example.com' from='example.com' id='reg1'>
   <query xmlns='jabber:iq:register'>
@@ -271,7 +333,7 @@
   <query xmlns='jabber:iq:register'>
     <username>juliet</username>
     <password>m1cro$oft</password>
-    <token>TOKEN</token>
+    <token>BADTOKEN</token>
   </query>
   <error type='cancel'>
     <invalid-token xmlns='urn:xmpp:invite:0'/>
@@ -283,7 +345,7 @@
   <query xmlns='jabber:iq:register'>
     <username>juliet</username>
     <password>m1cro$oft</password>
-    <token>TOKEN</token>
+    <token>OLDTOKEN</token>
   </query>
   <error type='cancel'>
     <token-expired xmlns='urn:xmpp:invite:0'/>