xeps/inbox/multistage-ibr.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Multi-stage IBR</title>
  <abstract>This specification defines an augmentation of In-Band Registration to allow for multiple stages of user input.</abstract>
  &LEGALNOTICE;
  <number>xxxx</number>
  <status>ProtoXEP</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XEP-0077</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  <author>
    <firstname>Stephen Paul</firstname>
    <surname>Weber</surname>
    <email>singpolyma@singpolyma.net</email>
    <jid>singpolyma@singpolyma.net</jid>
  </author>
  <revision>
    <version>0.0.1</version>
    <date>2016-02-03</date>
    <initials>spw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>When performing a registration using &xep0077;, multiple steps are sometimes needed so that the Host may ask questions based on information provided.  This specification defines an augmentation to XEP-0077 for this purpose.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>Multi-stage IBR must make it possible for a host to ask for further information in response to an initial registration request.  It must be usable with clients that only support XEP-0077, though possibly with a degraded user experience.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Entity Registers with a Host' anchor='usecases-register'>
    <p>This use case is identical to one in XEP-0077, except that it allows the Host to request further fields after an initial submission.  The examples have been altered to demonstrate one such case.  Errors are reported in the same way as XEP-0077, these examples show only a successful case.</p>

    <p>In order to determine which fields are required for registration with a host, an entity SHOULD first send an IQ get to the host. The entity SHOULD NOT attempt to guess at the required fields by first sending an IQ set, since the nature of the required data is subject to service provisioning.</p>
    <example caption='Entity Requests Registration Fields from Host'><![CDATA[
<iq type='get' id='reg1' to='sms.shakespeare.lit'>
  <query xmlns='jabber:iq:register'/>
</iq>
    ]]></example>

    <example caption='Host Returns Registration Fields to Entity'><![CDATA[
<iq type='result' id='reg1'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      Enter your phone number for verification
    </instructions>
    <phone/>
  </query>
</iq>
    ]]></example>

    <example caption='Entity Provides Required Information'><![CDATA[
<iq type='set' id='reg2'>
  <query xmlns='jabber:iq:register'>
    <phone>15550000</phone>
  </query>
</iq>
    ]]></example>
    <p>Note: The requesting entity MUST provide information for all of the elements (other than &lt;instructions/&gt;) contained in the IQ result.</p>
    <example caption='Host Informs Entity of More Fields Needed'><![CDATA[
<iq type='result' id='reg2'>
   <query xmlns='jabber:iq:register'>
     <instructions>
       Enter the code you received via SMS
     </instructions>
     <password/>
   </query>
</iq>
    ]]></example>
    <p>If the host requires additional information above and beyond the data elements specified in the schema, it SHOULD use Data Forms as described in the <link url='https://xmpp.org/extensions/xep-0077.html#extensibility'>Extensibility</link> section of XEP-0077.</p>
    <example caption='Entity Provides Further Information'><![CDATA[
<iq type='set' id='reg3'>
   <query xmlns='jabber:iq:register'>
     <password>123456</password>
   </query>
</iq>
    ]]></example>
    <example caption='Host Informs Entity of Successful Registration'><![CDATA[
<iq type='result' id='reg3'/>
    ]]></example>
    <p>When no more fields are requested, the registration is complete.</p>
  </section2>

  <section2 topic='Redirection' anchor='usecases-redirection'>
    <p>A given deployment MAY wish to redirect users to another medium (e.g., a website) for further stages of registration, rather than allowing in-band registration.  The recommended approach is to include only the <instructions/> element rather than the required fields or a data form in the IQ result, as well as a URL encoded using &xep0066;</p>
  <example caption='Host Redirects Entity to Web Registration'><![CDATA[
<iq type='result'
    from='sms.shakespeare.lit'
    id='reg2'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      To complete registration, visit https://www.shakespeare.lit/sms-verify
    </instructions>
    <x xmlns='jabber:x:oob'>
      <url>https://www.shakespeare.lit/sms-verify</url>
    </x>
  </query>
</iq>
  ]]></example>
  </section2>

  <section2 topic='Client Does Not Support Multi-stage Registration' anchor='usecases-fallback'>
    <p>To support clients that do not implement this specification, the Host SHOULD respond to a query for the registration fields according to what it still needs to know.</p>
    <example caption='Entity Requests Registration Fields from Host After One Stage'><![CDATA[
<iq type='get' id='reg3' to='sms.shakespeare.lit'>
  <query xmlns='jabber:iq:register'/>
</iq>
    ]]></example>

    <example caption='Host Returns Registration Fields to Entity Based on Current Stage'><![CDATA[
<iq type='result' id='reg3'>
   <query xmlns='jabber:iq:register'>
     <instructions>
       Enter the code you received via SMS
     </instructions>
     <password/>
   </query>
</iq>
    ]]></example>
    <p>Hosts SHOULD expire partial registrations after a reasonable amount of time, after which such a query would return the initial fields again.</p>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>No additional concerns over XEP-0077.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <p>This document requires no interaction with the &REGISTRAR;.</p>
</section1>
</xep>