mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-10 03:15:00 -05:00
354 lines
14 KiB
XML
354 lines
14 KiB
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>Easy User Onboarding</title>
|
|
<abstract>This document defines a protocol and URI scheme for user invitation in order to allow a third party to register on a server. The goal of this is to make onboarding for XMPP IM newcomers as easy as possible.</abstract>
|
|
&LEGALNOTICE;
|
|
<number>xxxx</number>
|
|
<status>ProtoXEP</status>
|
|
<type>Standards Track</type>
|
|
<sig>Standards</sig>
|
|
<approver>Council</approver>
|
|
<dependencies>
|
|
<spec>XMPP Core</spec>
|
|
<spec>XEP-0001</spec>
|
|
<spec>XEP-0050</spec>
|
|
<spec>XEP-0082</spec>
|
|
<spec>XEP-0077</spec>
|
|
<spec>XEP-0147</spec>
|
|
<spec>XEP-0379</spec>
|
|
</dependencies>
|
|
<supersedes/>
|
|
<supersededby/>
|
|
<shortname>N/A</shortname>
|
|
<author>
|
|
<firstname>Marc</firstname>
|
|
<surname>Schink</surname>
|
|
</author>
|
|
<revision>
|
|
<version>0.0.1</version>
|
|
<date>2018-01-10</date>
|
|
<initials>ms</initials>
|
|
<remark><p>First submission.</p></remark>
|
|
</revision>
|
|
</header>
|
|
<section1 topic='Introduction' anchor='intro'>
|
|
<p>Romeo is an active XMPP IM (Instant Messaging) user or the operator of
|
|
an XMPP server. He convinces Juliet (who may not have an XMPP account yet)
|
|
to install a client but she may still need to choose an XMPP server,
|
|
create an account, and add Romeo as a contact.
|
|
This specification defines two ways for Romeo to simplify this process for Juliet:</p>
|
|
<section2 topic='User Invitation'>
|
|
<p>If Romeo is an XMPP user, he can create an out-of-band link (URI)
|
|
which allows Juliet to:</p>
|
|
<ol>
|
|
<li>Download an XMPP client (if needed).</li>
|
|
<li>Optionally register an account with Romeo's server (if permitted by
|
|
the server rules), or with a public server.</li>
|
|
<li>Establish a mutual presence subscription between Romeo and Juliet.</li>
|
|
</ol>
|
|
<p>The process is designed to automatically skip steps that Juliet already
|
|
completed, to make the overall experience as smooth as possible.</p>
|
|
</section2>
|
|
<section2 topic='Account Creation'>
|
|
<p>If Romeo is an administrator of an XMPP server, he can create an
|
|
out-of-band link (URI) which allows Juliet to:</p>
|
|
<ol>
|
|
<li>Download an XMPP client (if needed).</li>
|
|
<li>Register an account on Romeo's server with a user name defined by
|
|
Romeo and a password not known to Romeo.</li>
|
|
<li>Establish a mutual presence subscription between Romeo and Juliet.</li>
|
|
</ol>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Requirements' anchor='reqs'>
|
|
<p>This specification makes use of XMPP URIs. The basic URI scheme for XMPP
|
|
is defined in &rfc5122; and extended in &xep0147; and &xep0379;.
|
|
Furthermore, this heavily builds upon the blocks provided in
|
|
<cite>XEP-0379</cite> for landing page and roster subscription.
|
|
</p>
|
|
<p>
|
|
To create out-of-band invitation links, Romeo's server needs to implement
|
|
the &xep0050; commands specified in the following section, and his client
|
|
must be able to execute them.
|
|
</p>
|
|
<p>
|
|
Furthermore, Romeo's server SHOULD provide a HTTPS service hosting the
|
|
landing page.
|
|
</p>
|
|
</section1>
|
|
<section1 topic='Discovery' anchor='discover'>
|
|
<example caption="Discover available ad-hoc commands"><![CDATA[
|
|
<iq type='get' from='romeo@example.com' to='example.com' id='disco'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://jabber.org/protocol/commands'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Discovery result for available ad-hoc commands"><![CDATA[
|
|
<iq type='result' to='romeo@example.com' from='example.com' id='disco'>
|
|
<query xmlns='http://jabber.org/protocol/disco#items'
|
|
node='http://jabber.org/protocol/commands'>
|
|
<item jid='example.com'
|
|
node='invite'
|
|
name='Invite user'/>
|
|
<item jid='example.com'
|
|
node='create-account'
|
|
name='Create account'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section1>
|
|
<section1 topic='Glossary' anchor='glossary'>
|
|
<p>OPTIONAL.</p>
|
|
</section1>
|
|
<section1 topic='Use Cases' anchor='usecases'>
|
|
<section2 topic='User Invitation' anchor='invitation'>
|
|
<example caption="Exceute user invitation command"><![CDATA[
|
|
<iq type='set' from='romeo@example.com' to='example.com' id='exec1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='invite'
|
|
action='execute'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="User invitation finished"><![CDATA[
|
|
<iq type='result' to='romeo@example.com' from='example.com' id='exec2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
node='invite'
|
|
status='completed'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<item>
|
|
<field var='uri'>
|
|
<value>xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=true</value>
|
|
</field>
|
|
<field var='landing-url'>
|
|
<value>https://example.com/invite/#TOKEN</value>
|
|
</field>
|
|
<field var='expire'>
|
|
<value>2017-11-06T02:56:15Z</value>
|
|
</field>
|
|
</item>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
<p>A server MUST provide the <strong>uri</strong> field which contains an
|
|
XMPP URI of the following format:</p>
|
|
<code>xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=true</code>
|
|
<p>The <strong>ibr</strong> query component in the XMPP URI indicates that
|
|
the invitee is allowed to create an account on the Romeo's server.
|
|
If the server does not support or allow in-band registration for invited
|
|
users, the server MUST omit the <strong>ibr</strong> query component.</p>
|
|
<p>Additionally, the server SHOULD provide the <strong>landing-url</strong>
|
|
field which contains an HTTPS URL of a web-based landing page as described
|
|
in &xep0379; § 3.3. The URL format may differ from the example shown here
|
|
depending on where the landing page is hosted.</p>
|
|
<p>A server MAY provide a field which provides the expiration date of the
|
|
generated token. The expiration date MUST conform to the DateTime profile
|
|
specified in &xep0082;. If the field is not provided, the token does not
|
|
expire.</p>
|
|
<section2 topic='Account Creation' anchor='account-creation'>
|
|
<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'
|
|
node='create-account'
|
|
action='execute'/>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Service returns form for account creation"><![CDATA[
|
|
<iq type='result' to='romeo@example.com' from='example.com' id='exec1'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
sessionid='config:20020923T213616Z-700'
|
|
node='create-account'
|
|
status='executing'>
|
|
<actions execute='complete'>
|
|
<complete/>
|
|
</actions>
|
|
<x xmlns='jabber:x:data' type='form'>
|
|
<field var='username' label='Username' type='text-single'/>
|
|
<field var='roster-subscription' label='Roster subscription' type='boolean'/>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>A server MAY require a username to be specified for account creation.
|
|
In this case, the server MUST add the <required/> element to the
|
|
username field.
|
|
The username MUST be a valid localpart as defined in &rfc6122; §2.3.</p>
|
|
<example caption="Account creation with specified username"><![CDATA[
|
|
<iq type='set' from='romeo@example.com' to='example.com' id='exec2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
sessionid='config:20020923T213616Z-700'
|
|
node='create-account'>
|
|
<x xmlns='jabber:x:data' type='submit'>
|
|
<field var='username'>
|
|
<value>juliet</value>
|
|
</field>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Account creation finished"><![CDATA[
|
|
<iq type='result' to='romeo@example.com' from='example.com' id='exec2'>
|
|
<command xmlns='http://jabber.org/protocol/commands'
|
|
sessionid='config:20020923T213616Z-700'
|
|
node='create-account'
|
|
status='completed'>
|
|
<x xmlns='jabber:x:data' type='result'>
|
|
<item>
|
|
<field var='uri'>
|
|
<value>xmpp:juliet@example.com?register;preauth=TOKEN</value>
|
|
</field>
|
|
<field var='landing-url'>
|
|
<value>https://example.com/invite/#TOKEN</value>
|
|
</field>
|
|
<field var='expire'>
|
|
<value>2017-11-06T02:56:15Z</value>
|
|
</field>
|
|
</item>
|
|
</x>
|
|
</command>
|
|
</iq>
|
|
]]></example>
|
|
<p>The server's response for account creation is the same as for user
|
|
invitation except for the format of the <strong>uri</strong> field which
|
|
contains an XMPP URI of the following format:</p>
|
|
<code>xmpp:juliet@example.com?register;preauth=TOKEN</code>
|
|
<p>If no username was specified during the account creation process, the
|
|
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>
|
|
</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>
|
|
<example caption="Retrieving registration fields"><![CDATA[
|
|
<iq type='get' id='reg1' to='example.com'>
|
|
<query xmlns='jabber:iq:register'>
|
|
<preauth xmlns='urn:xmpp:invite:0'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption="Receiving registration fields"><![CDATA[
|
|
<iq type='result' to='romeo@example.com' from='example.com' id='reg1'>
|
|
<query xmlns='jabber:iq:register'>
|
|
<username/>
|
|
<password/>
|
|
<token/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Registration process aborted (invalid token)'><![CDATA[
|
|
<iq type='error' from='example.com' id='reg1'>
|
|
<query xmlns='jabber:iq:register'>
|
|
<username>juliet</username>
|
|
<password>m1cro$oft</password>
|
|
<token>TOKEN</token>
|
|
</query>
|
|
<error type='cancel'>
|
|
<invalid-token xmlns='urn:xmpp:invite:0'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<example caption='Registration process aborted (token expired)'><![CDATA[
|
|
<iq type='error' from='example.com' id='reg1'>
|
|
<query xmlns='jabber:iq:register'>
|
|
<username>juliet</username>
|
|
<password>m1cro$oft</password>
|
|
<token>TOKEN</token>
|
|
</query>
|
|
<error type='cancel'>
|
|
<token-expired xmlns='urn:xmpp:invite:0'/>
|
|
</error>
|
|
</iq>
|
|
]]></example>
|
|
<p>After the invitee has successfully registered on the inviter's server
|
|
and roster subscription is enabled for account creation, the server MUST
|
|
use roster pushes as defined in &rfc6121; §2.1.6 in order to inform the
|
|
inviter about the invitee's new account without the need to reconnect.</p>
|
|
<example caption="Push roster item of invitee to inviter"><![CDATA[
|
|
<iq type='set' from='romeo@example.com' id='push'>
|
|
<query xmlns='jabber:iq:roster'>
|
|
<item subscription='both' jid='juliet@example.com'/>
|
|
</query>
|
|
</iq>
|
|
]]></example>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Business Rules' anchor='rules'>
|
|
<section2 topic='Fallback to Client-Side PARS'>
|
|
<p>If the inviter's server does not support user invitation, the client
|
|
application SHOULD silently fall back to &xep0379; for a good user
|
|
experience.</p>
|
|
</section2>
|
|
<section2 topic='Account Creation'>
|
|
<p>If a username was specified during the account creation process, the
|
|
server SHOULD NOT create an account on the server until the invitee
|
|
actually registers it with the corresponding token.
|
|
The server MUST reserve the username at least until the corresponding
|
|
token expires.</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Implementation Notes' anchor='impl'>
|
|
<section2 topic='XMPP Server Suggestion for Invitees'>
|
|
<p>If the invitee opens the invitation URI and chooses to create a new
|
|
account, the client MUST use the inviter's server as default if the
|
|
server advertises in-band registration support via the
|
|
<strong>ibr=true</strong> query compontent.</p>
|
|
</section2>
|
|
</section1>
|
|
<section1 topic='Accessibility Considerations' anchor='access'>
|
|
<p>OPTIONAL.</p>
|
|
</section1>
|
|
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
|
<p>OPTIONAL.</p>
|
|
</section1>
|
|
<section1 topic='Security Considerations' anchor='security'>
|
|
<p>See security considerations in &xep0379;.</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>As authorized by &xep0147;, the XMPP Registrar maintains a registry of
|
|
queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
|
|
<p>The key-value parameter <strong>preauth</strong> is added to the
|
|
<strong>register</strong> query action as defined in &xep0077;</p>
|
|
<code><![CDATA[
|
|
<querytype>
|
|
<name>register</name>
|
|
...
|
|
<key>
|
|
<name>preauth</name>
|
|
<desc>the token used to allow one-time in-band registration on the inviter's server</desc>
|
|
</key>
|
|
</querytype>
|
|
]]></code>
|
|
|
|
<p>In addition to the <strong>preauth</strong> key-value parameter define
|
|
in &xep0379;, the <strong>ibr</strong> parameter is added to the
|
|
<strong>roster</strong> query action.</p>
|
|
<code><![CDATA[
|
|
<querytype>
|
|
<name>roster</name>
|
|
...
|
|
<key>
|
|
<name>ibr</name>
|
|
<value>true</value>
|
|
<desc>the parameter to indicate that the token allows the invitee to create an account on the inviter's server via in-band registration</desc>
|
|
</key>
|
|
</querytype>
|
|
]]></code>
|
|
</section1>
|
|
<section1 topic='XML Schema' anchor='schema'>
|
|
<p>REQUIRED for protocol specifications.</p>
|
|
</section1>
|
|
</xep>
|