aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarc Schink <xmpp-dev@marcschink.de>2018-01-10 12:18:41 +0100
committerMarc Schink <xmpp-dev@marcschink.de>2018-01-10 12:18:41 +0100
commit36f9b7a3326f5f5dc0d6a980123527a2de58e326 (patch)
tree7e295a7956918b865e92bb099b141d39e77c772d
parent5968e64760f7f60ce1176ec3a99255f834ec021c (diff)
ProtoXEP: User invitationuser_invite_public
-rw-r--r--inbox/user-invite.xml320
1 files changed, 320 insertions, 0 deletions
diff --git a/inbox/user-invite.xml b/inbox/user-invite.xml
new file mode 100644
index 0000000..da6c42e
--- /dev/null
+++ b/inbox/user-invite.xml
@@ -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 &lt;required/&gt; 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>