mirror of
https://github.com/moparisthebest/xeps
synced 2024-11-21 08:45:04 -05:00
ProtoXEP: User invitation
This commit is contained in:
Marc Schink
parent
5968e64760
commit
36f9b7a332
320
inbox/user-invite.xml
Normal file
320
inbox/user-invite.xml
Normal file
@ -0,0 +1,320 @@
|
||||
<?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>XEP Template</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>
|
||||
</dependencies>
|
||||
<supersedes/>
|
||||
<supersededby/>
|
||||
<shortname>N/A</shortname>
|
||||
<author>
|
||||
<firstname>Marc</firstname>
|
||||
<surname>Schink</surname>
|
||||
</author>
|
||||
<revision>
|
||||
<version>0.0.1</version>
|
||||
<date>2017-11-03</date>
|
||||
<initials>ms</initials>
|
||||
<remark><p>First draft.</p></remark>
|
||||
</revision>
|
||||
</header>
|
||||
<section1 topic='Introduction' anchor='intro'>
|
||||
<p>Romeo is an active XMPP IM (Instant Messaging) user. He convinces Juliet
|
||||
(who may not have an XMPP account yet) to install a client but she may
|
||||
still need to choose a XMPP server and create an account.
|
||||
This specification defines two ways to simplify this process for Juliet:</p>
|
||||
<section2 topic='User Invitation'>
|
||||
</section2>
|
||||
<section2 topic='Account Creation'>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Requirements' anchor='reqs'>
|
||||
<p>STRONGLY RECOMMENDED.</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>
|
||||
Loading…
Reference in New Issue
Block a user