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>
  <legal>
    <copyright>This XMPP Extension Protocol is copyright (c) 2016 by the XMPP Standards Foundation (XSF).</copyright>
    <permissions>Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the &quot;Specification&quot;), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.</permissions>
    <warranty>## NOTE WELL: This Specification is provided on an &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##</warranty>
    <liability>In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.</liability>
    <conformance>This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at &lt;<link url='http://xmpp.org/extensions/ipr-policy.shtml'>http://xmpp.org/extensions/ipr-policy.shtml</link>&gt; or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).</conformance>
  </legal>
  <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>