From f9044757e6e75eaf072070a9bbd64d5a976a26ca Mon Sep 17 00:00:00 2001 From: Jonas Wielicki Date: Thu, 25 Jan 2018 09:08:59 +0100 Subject: [PATCH] Accept inbox/user-invite.xml as XEP-0401 --- xep-0401.xml | 442 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 442 insertions(+) create mode 100644 xep-0401.xml diff --git a/xep-0401.xml b/xep-0401.xml new file mode 100644 index 00000000..2ae58636 --- /dev/null +++ b/xep-0401.xml @@ -0,0 +1,442 @@ + + +%ents; +]> + + +
+ Easy User Onboarding + 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. + &LEGALNOTICE; + 0401 + Experimental + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0050 + XEP-0082 + XEP-0077 + XEP-0147 + XEP-0379 + + + + N/A + + Marc + Schink + + + 0.1.0 + 2018-01-25 + XEP Editor (jwi) + Accepted by vote of Council on 2018-01-17. + + + 0.0.1 + 2018-01-10 + ms +

First submission.

 + +
+ +

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:

+ +

If Romeo is an XMPP user, he can create an out-of-band link (URI) + which allows Juliet to:

+
    +
  1. Download an XMPP client (if needed).
    2. +
  2. Optionally register an account with Romeo's server (if permitted by + the server rules), or with a public server.
    3. +
  3. Establish a mutual presence subscription between Romeo and Juliet.
    4. +
+

The process is designed to automatically skip steps that Juliet already + completed, to make the overall experience as smooth as possible.

+ + +

If Romeo is an administrator of an XMPP server, he can create an + out-of-band link (URI) which allows Juliet to:

+
    +
  1. Download an XMPP client (if needed).
    2. +
  2. Register an account on Romeo's server with a user name defined by + Romeo and a password not known to Romeo.
    3. +
  3. Establish a mutual presence subscription between Romeo and Juliet.
    4. +
+ + + +

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 + XEP-0379 for landing page and roster subscription. +

+

+ 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. +

+

+ Furthermore, Romeo's server SHOULD provide a HTTPS service hosting the + landing page. +

+ + +

Romeo can query his server for the availability of "User Invitation" and + "Account Creation" commands:

+ + + +]]> +

TODO: use appropriate node namespace.

+ + + + + + +]]> +

When performing the account creation, Juliet's client needs to ensure + that the server supports the extended IBR protocol with a <preauth> + token: TODO

+ + +

OPTIONAL.

+ + + +

A user can execute the 'invite' command to obtain a new invitation link + with a unique invitation token.

+ + + +]]> + + + + + + xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=y + + + https://example.com/invite/#TOKEN + + + 2017-11-06T02:56:15Z + + + + + +]]> +

The token should be unique, sufficiently + long and generated by a strong random number generator.

+

A server MUST provide the uri field which contains an + XMPP URI of the following format:

+ xmpp:inviter@example.com?roster;preauth=TOKEN;ibr=y +

The ibr query component in the XMPP URI indicates that + the invitee is allowed to create an account on Romeo's server, using the + 'preauth' token. + If the server does not support or allow in-band registration for invited + users, the server MUST omit the ibr query component.

+

Additionally, the server SHOULD provide the landing-url + 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.

+

If the server omits the landing-page field, Romeo's + client SHOULD generate an appropriate landing page URL hosted by the + client developer or a trusted third party.

+

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.

+

Romeo's client should provide adequate means to export the + landing-page URL, possibly accompanied with a short + description and the expire information, so that Romeo can + share it with Juliet by other means than XMPP, like e-mail or a QR code.

+ + +

The landing page that the generated URL points to should correspond to + the format described in XEP-0379 §3.3, and it needs to + convey the following information:

+
    +
  • A short text that this is an XMPP invitation from Romeo.
    • +
  • A client recommendation (based on the detected web browser/OS) with download links.
    • +
  • A prominent button that activates the encoded xmpp: link.
    • +
+

If the landing page is hosted by Romeo's server, the server MAY display + additional information based on the supplied TOKEN value, like the name + of the inviter or validity information.

+ + +

If Juliet does not have an XMPP client installed, she will not be able + to open the xmpp: link from the invitation page. + For this case, the landing page needs to indicate that a client must be + installed first, and that the link will not work as intended without. + The automatic installation of an appropriate IM client when a user + clicks on an xmpp: is outside of the scope of this + document.

+

With an XMPP client installed, Juliet can open the + xmpp: link and have the client process it + appropriately, as follows:

+ +

If Juliet's client is already configured with an account, the default + action for the presented + xmpp:inviter@example.com?roster;... URI is to add the + inviter to Juliet's roster. This should be performed as described in + §3.4 of XEP-0379, by sending a presence subscription + request containing the 'preauth' token.

+

If Juliet already has Romeo in her roster, her client should open the + appropriate chat interface instead.

+ + +

If Juliet's client does not have an XMPP account configured, she + needs to login or register an account first. Therefore, the client + should provide an interface with the following options:

+
    +
  • Login with an existing XMPP account.
    • +
  • Register an account with Romeo's server (if the URI contains a + ibr=y parameter).
    • +
  • Register an account with a public or client-endorsed server.
    • +
+

If the xmpp: URI provided by Romeo contains the + ibr=y parameter, it indicates that the server + supports the Pre-Authenticated In-Band + Registration defined in this document. If Juliet chooses this + approach, the server will ensure that after the registration, Romeo is + added to her roster with a full presence subscription.

If + Juliet chooses to login or register with a different server, her + client must complete the respective process and issue a subscription + request as described in §3.4 of XEP-0379.

+ + + +

If Romeo is the administrator of an XMPP server, he might want to + ensure that Juliet obtains an account on this server, with a username + defined either by Romeo or by Juliet, and in a way that does not require + the out-of-band communication of user passwords.

+

TODO: description of overall process steps, design motivation.

+ + + +]]> + + + + + + + + + + + +]]> +

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.

+ + + + + juliet + + + + +]]> + + + + + + xmpp:juliet@example.com?register;preauth=TOKEN + + + https://example.com/invite/#TOKEN + + + 2017-11-06T02:56:15Z + + + + + +]]> +

The server's response for account creation is the same as for user + invitation except for the format of the uri field which + contains an XMPP URI of the following format:

+ xmpp:juliet@example.com?register;preauth=TOKEN +

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:

+ xmpp:example.com?register;preauth=TOKEN +

TODO: note about sensitivity of TOKEN

+ + +

In order to allow invited users to register on a server, the + registration processs as defined in &xep0077; needs to be extended. The + invited user's client MUST add a <preauth> element in the 'TODO' + namespace to the 'jabber:iq:register' query in order to inform the + server that it wants to perform Pre-Authenticated IBR:

+ + + + + +]]> +

If the server supports and is ready to perform Pre-Authenticated IBR, + it MUST add a <token> element to the response (TODO: 'token' or + 'preauth'?):

+ + + + + + + +]]> + + + juliet + m1cro$oft + BADTOKEN + + + + + +]]> + + + juliet + m1cro$oft + OLDTOKEN + + + + + +]]> +

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.

+ + + + + +]]> + + + + +

If the inviter's server does not support user invitation, the client + application SHOULD silently fall back to &xep0379; for a good user + experience.

+ + +

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.

+ + + + +

If the invitee opens an invitation URI with ibr=y and + chooses to create a new account, the client SHOULD pre-fill the + inviter JID's domain part as the new account's domain. The client MAY + provide a mechanism to enter or choose a different server, though.

+ + + +

OPTIONAL.

+ + +

OPTIONAL.

+ + +

See security considerations in &xep0379;.

+ + +

This document requires no interaction with &IANA;.

+ + +

As authorized by &xep0147;, the XMPP Registrar maintains a registry of + queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).

+

The key-value parameter preauth is added to the + register query action as defined in &xep0077;

+ + register + ... + + preauth + the token used to allow one-time in-band registration on the inviter's server + + +]]> + +

In addition to the preauth key-value parameter define + in &xep0379;, the ibr parameter is added to the + roster query action.

+ + roster + ... + + ibr + y + the parameter to indicate that the token allows the invitee to create an account on the inviter's server via in-band registration + + +]]> + + +

REQUIRED for protocol specifications.

+ +