From 5679b6eb0f1652b280f839572f26582f8c3175d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Sch=C3=A4fer?= Date: Tue, 24 Nov 2020 18:45:52 +0100 Subject: [PATCH] Accept inbox/ibr-token.xml as XEP-0445 --- xep-0445.xml | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 xep-0445.xml diff --git a/xep-0445.xml b/xep-0445.xml new file mode 100644 index 00000000..e50a8dbb --- /dev/null +++ b/xep-0445.xml @@ -0,0 +1,199 @@ + + +%ents; +]> + + +
+ Pre-Authenticated In-Band Registration + This document extends the In-Band-Registration protocol to use + invitation tokens, e.g. for registering accounts on non-public + servers. + + &LEGALNOTICE; + 0445 + Experimental + Standards Track + Standards + Council + + XMPP Core + XEP-0077 + XEP-0147 + XEP-0379 + XEP-0401 + + + + ibr-token + + Georg + Lukas + + + 0.2.0 + 2020-11-24 + XEP Editor (jsc) + Accepted by vote of Council on 2020-11-04. + + + 0.1.0 + 2020-10-28 + gl + First version based on XEP-0401. + +
+ +

There are two typical mechanisms to register an account on an XMPP server:

+
    +
  • Out-of-band account creation, after which the account JID and password + need to be manually entered into an XMPP client, and
    • +
  • &xep0077; (IBR) where an account is created and fully configured right + from the XMPP client.
    • +
+

The IBR mechanism is much more convenient for users, but also opens up + the server to abuse, e.g. due to the mass-registration of spam bot + accounts. Captchas, while heavily impacting well-intentioned users, are + not a reliable mechanism to prevent abuse. This specification allows to + restrict the IBR mechanism by requiring a registration token, e.g. for + giving users access to a private server, without exposing their password + to the server administrator.

+

This specification is part of a series of documents aiming at improving + user onboarding:

+
    +
  • &xep0379; to automatically accept roster subscriptions based on a + token.
    • +
  • &xep0401; to generate tokens that can be used for authenticating IBR.
    • +
+

While this specification is designed to work together with &xep0401;, it + can be used with invitation tokens obtained by any other mechanism. XMPP + URIs can then be used out-of-band to deliver the invitation to a new user.

+

A client that obtains such an XMPP URI should allow the user to register + an XMPP account with the server that generated the URI.

+ + + +

A client that implements this specification needs to understand the + &xep0147; specification, to make use of the register query + action and the preauth parameter. Three URI formats + are defined.

+ +

An invitation to register an account can contain a specific XMPP + address (with a pre-defined user account name) to be registered. A + client should populate the address field in the IBR dialog with this + address and disallow changing the address.

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

An invitation to register an account can contain just the server domain + to register on. A client should populate the address field in the IBR + dialog with this domain and allow entering the desired account name.

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

A contact invitation with a registration token (&xep0379;) might + indicate that the token can also be used to register an account on that + server (ibr=y). If the receiving client already has an account + configured, it may skip account registration and simply add the contact + as defined in XEP-0379. The client may also register a new + account on the domain of the proposed contact, allowing the user to + enter the desired account name.

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

While a registration URI is an indication that the respective server + supports Pre-Authenticated IBR, a URI might be manipulated and is not + guaranteed to be reliable.

+

Therefore, when performing the account creation, the client needs to + ensure that the server supports the Pre-Authenticated IBR protocol, as denoted by + the <register xmlns='urn:xmpp:ibr-token:0'> + stream feature:

+ + + EXTERNAL + SCRAM-SHA-1-PLUS + SCRAM-SHA-1 + PLAIN + + + + +]]> + + +

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 needs to connect to the server and check that the + invitation stream feature + (<register xmlns='urn:xmpp:ibr-token:0'>) is present. + After that, the client initiates the registration flow by sending the + preauth token to the server:

+ + + +]]> +

Upon receiving the preauth request, the server must validate that the + token is acceptable for account registration. However, single-use tokens + MUST NOT be considered used until the actual registration has succeeded. +

+

In addition, if the token has an expiration time, it MUST only be + checked at this point. Subsequent actions performed by the client during + the current session that require a valid token MUST NOT be rejected due + to token expiry. +

+

If the token is acceptable, the server responds with success, and + indicates the client may now proceed with account registration: +

+ +]]> +

If the token provided by the client was unknown, invalid or expired, the + server should return an appropriate error to the client:

+ + + + The provided token is invalid or expired + + +]]> +

In the success case, the client proceeds with registration as defined in + &xep0077;. If the token is rejected by the server, the client still MAY + attempt to perform IBR if the server allows that.

+ + +

If a username was specified when creating an invitation token, 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.

+ + + +

See security considerations in &xep0379;.

+ + +

This document requires no interaction with &IANA;.

+ + +

This document only makes use of the XMPP URI elements defined in + &xep0401;

+ + +

REQUIRED for protocol specifications.

+ +