XEP-0379: Pre-Authenticated Roster Subscription

This document defines a protocol and URI scheme for pre-authenticated roster links that allow a third party to automatically obtain the user's presence subscription. The goal of this is to make onboarding of new XMPP IM contacts as easy as possible.
Georg Lukas
© 2016 – 2021 XMPP Standards Foundation. SEE LEGAL NOTICES.


NOTICE: This document is currently within Last Call or under consideration by the XMPP Council for advancement to the next stage in the XSF standards process. The Last Call ends on 2021-10-20. Please send your feedback to the standards@xmpp.org discussion list.
Standards Track
0.3.3 (2021-03-04)
Document Lifecycle
  1. Experimental
  2. Proposed
  3. Stable
  4. Final

1. Introduction

Romeo is an active XMPP IM (Instant Messaging) user. He convinces Juliet (who doesn't have an XMPP account yet) to install a client and register with some server. Now, Romeo only needs to create a mutual presence subscription with her, without yet knowing her JID.

This specification allows Romeo to create an out-of-band link (URI) which, when opened in Juliet's (or another user's) client, will:

The perceivable effect is that with a single click, Romeo and Juliet become "friends" in terms of XMPP presence subscription.

2. Requirements

This specification makes use of XMPP URIs. The basic URI scheme for XMPP is defined in RFC 5122 [1] and extended in XMPP URI Query Components (XEP-0147) [2] to support different actions like "roster" for roster addition and "subscribe" for presence subscription.

3. Pre-Authenticated Roster Subscription

The process of mutual roster addition and subscription involves multiple steps:

  1. Generation of invitation link
  2. Out-of-band transmission and presentation of the link
  3. Subscription request to the user by the link receiver (new contact)
  4. Approval by the user and mutual subscription request
  5. Approval by the new contact

The general idea of the protocol and the details of the individual steps are outlined in the following.

3.1 General Idea

As Romeo doesn't know Juliet's JID, he needs to send an out-of-band invitation. Later, his client needs to match an incoming subscription request to this invitation, so it can perform a secure automatic roster addition and subscription approval. This matching is accomplished by means of an authentication token, which is generated by Romeo's client, added to the invitation link and then carried over into the subscription request eventually made by Juliet's client. Romeo's client can then compare the token received in a subscription request to the list of issued tokens, and automatically approve the subscription.

Successful PARS Protocol Flow
Romeo          mongatague.net  capulet.net     Juliet
   |              |               |               |
   | Send out-of-band invitation link             |
   | xmpp:romeo@montague.net?roster;preauth=token |
   |- - - - - - - - - - - - - - - - - - - - - - ->|
   |              |               |    roster add |
   |              |               |<--------------|
   |       presence subscription request w/ token |
   |  <presence><preauth token="..."/></presence> |
   | (token validation check)     |               |
   | presence subscribed          |               |
   | roster add   |               |               |
   |------------->|               |               |
   | presence subscription request|               |
   |              |               (auto approval) |
   |              |           presence subscribed |

Whenever Romeo wishes to invite somebody to his roster, his client will generate an invitation link that contains a new authentication token. This document extends the "roster" URI action defined in XEP-0147 with a new key-value parameter named "preauth" to store the generated token. Romeo's client will create an xmpp: link containing Romeo's JID, the "roster" action, the "preauth" parameter with the token value, and optionally a "name" parameter with the suggested display name.

Example 1. Invitation Link with Roster Action and Authentication Token

If the "preauth" parameter is present, the processing client is supposed not only to add the user to the roster, but also to automatically send a subscription request containing the authentication token.

Server-side implementation: it is possible (but out-of-scope for this document), to let the user's server handle generation of links as well as automatic approval of qualified subscription requests. One such approach is documented in Easy User Onboarding (XEP-0401) [3].

As Romeo doesn't know Juliet's JID in advance, he needs to use an out-of-band method (like e-mail, QR codes or NFC) to transmit the invitation link to Juliet. While these methods allow transmission of xmpp: URIs, there is no mechanism to ensure that Juliet actually has a client installed that can open the URI.

One way to solve this problem is to present Juliet with a web-based landing page that contains the following elements:

There are multiple options where such a landing page could be hosted:

  1. XSF: a central place would provide a common ground for a curated client list and ensure long-term availability. However, the operator would be able to collect metadata and abuse authentication tokens.
  2. Client developer: the developer of Romeo's client can provide a landing page for invitation requests created with this client. This is a feasible short-term solution and allows to recommend the same client as used by the link sender. However, it shares the privacy objections of the XSF solution and can not guarantee long-term availability of the service. If the client development shuts down, invitation links created with the client will cease working.
  3. User's server: this is the optimal long-term solution, as the user's server is already entrusted with the relevant metadata and will exist at least as long as the user's account on that server. However, this requires an additional server component to query for invitation URIs and a web server hosting the landing page. Furthermore, the server operator needs to maintain the list of recommended clients.
Example 2. Developer-Hosted Landing Page Generated with Fictitious JuicyXMPP Client

A possible screen representation of the landing page would be:

Romeo Montague has invited you to chat

Add "Romeo Montague"

If this link does not work, you need to install and configure an XMPP client. Please visit this page again afterwards. Choose one of these for your Tomato OS:

Check the full list of XMPP clients.

No further action is required if you do not know Romeo Montague or do not want to chat with them.

XMPP is a provider-independent form of instant messaging. That means you can pick from many different clients and have a free choice of server operators to communicate with Romeo Montague.

When Juliet opens the xmpp: URI (or the according client-supported landing page URI) in her client, the client should perform the usual roster addition action, i.e. display a dialog allowing to edit the entry or to cancel the process. If Juliet completes the roster addition, the client SHOULD also send a subscription request to Romeo. This request SHOULD contain a 'preauth' element containing the authentication token from the invitation link.

Example 3. Subscription Request with Pre-Authenticated Roster Subscription Element
<presence to='romeo@montague.net' type='subscribe'>
  <preauth xmlns='urn:xmpp:pars:0' token='1tMFqYDdKhfe2pwp' />

If Juliet's server supports subscription pre-approval, the client SHOULD additionally pre-approve Romeo:

Example 4. Juliet Pre-approves Romeo
<presence to='romeo@montague.net' type='subscribed' />

If Juliet's server does not indicate pre-approval support, her client SHOULD store Romeo's JID in a local auto-approval list, together with an appropriate expiration time.

3.5 Approval by the User and Mutual Subscription Request

When Romeo's client receives a subscription request containing a 'preauth' element, it needs to extract the authentication token and check if the token is a valid one and was previously issued by the client (see security considerations below).

Example 5. Subscription Request With Tokens Received by Romeo
<presence to='romeo@montague.net' from='juliet@capulet.net' type='subscribe'>
  <preauth xmlns='urn:xmpp:pars:0' token='1tMFqYDdKhfe2pwp' />

If the token is considered valid, the client SHOULD automatically approve the subscription request, add the sender of the subscription request to the roster and send a subscription request of its own.

Example 6. Automatic Approval and Response Subscription Request
<presence to='juliet@capulet.net' type='subscribed' />
<presence to='juliet@capulet.net' type='subscribe' />

3.6 Approval by the New Contact

If Juliet's server supports pre-approval, it will automatically handle the incoming subscription request and issue a roster push. Otherwise, Juliet's client will receive the subscription request:

Example 7. Mutual Subscription Request
<presence from='romeo@montague.net' to='juliet@capulet.net' type='subscribe' />

Juliet's client MUST ensure that the sender JID is contained in the auto-approval list before automatically approving the request. Otherwise, it has to fallback to the normal subscription approval process.

4. Business Rules

4.1 Fallback to Manual Process

An implementation of this protocol MUST allow for a "graceful degradation" to the manual subscription approval process. If a client receives a malformed or unknown 'preauth' token, it MUST ignore it and act as if no preauth token was contained.

4.2 No Expectation of Immediate Approval

When sending a pre-authenticated subscription request, the contact's client MUST NOT expect an immediate successful approval. If the user's issuing client is currently offline, or if the token has expired, a manual approval will be performed. Therefore, the contact's client should use the same mechanism as before to indicate an unidirectional subscription.

5. Security Considerations

5.1 Token Generation

As the authentication token grants automatic addition to Romeo's roster and automatic approval of presence subscription, the token SHOULD be created with a cryptographically secure random number generator [4] and provide sufficient entropy to make brute-force attacks infeasible. It is suggested to generate at least 80 bits of entropy, and to use an encoding that can be easily encoded as part of an URI (e.g. Base-32).

It is possible to use a different token generation scheme like Security Assertion Markup Language [6] or JWT (RFC 7519 [7]). In such a case, the issuer must ensure a comparable security level and limit token reuse.

5.2 Checking Token Validity

To limit the potential for abuse, the token SHOULD be limited in as follows:

If a token is considered invalid (due to failing any of the above conditions, or for other reasons), a client MUST fall back to manual roster addition and manual subscription approval.

5.3 Interception of Links

A Monkey-in-the-Middle attacker who gains access to the invitation link can manipulate its fields or redeem the link themselves. However, this is true for all communication performed using the chosen medium and is out of scope for this document.

Ideally, Romeo's client should highlight automatically-added roster items and provide an easy mechanism to remove them and cancel their subscription.

5.4 Display Names

An attacker can lure the user by providing an invitation link with a 'name' parameter that does not match the JID. Therefore, a client SHOULD always display both the JID and the proposed display name when adding a roster item.

When the user's client automatically approves a subscription, it SHOULD add the new contact to the roster without a 'name' or with the 'name' equal to the JID, to prevent impersonation attacks.

6. Usability Considerations

6.1 Use of Multiple Clients

If a user is logged in with multiple clients, some of their clients will receive a subscription request with an unknown token. In this case, a client MAY delay the user notification for a short time, to allow another logged-in client to automatically handle the subscription request.

6.2 Opening the Landing Page in an App

Some mobile device platforms allow an app to register itself as a handler for certain URIs. This allows an XMPP client to register for xmpp: URIs, but also to redirect handling of certain HTTP/HTTPS URIs. A mobile client SHOULD register for the associated landing page URIs and properly handle the contained invitations. For example, the JuicyXMPP client should register a handler for https://juicyxmpp.example/i/*, and present the "Add to roster" dialog if such a link is opened. A client MAY register for the landing page URIs of other providers after obtaining the operators' approval.

6.3 Invitation Link Volatility

By default, Romeo's client should generate personal invitation links that can only be redeemed once, and only for a limited time. This fact SHOULD be indicated by the client UI to Romeo.

If a client allows customization of the validity time or the number of uses for a given invitation token, it SHOULD provide clear language to indicate that.

6.4 Tagging of Auto-Added Contacts

When a new contact is added automatically by the client, it SHOULD indicate this fact to the user, and allow the user to rename / group the contact appropriately. One possible way to achieve this is by putting all auto-added contacts into a special roster group, and by automatically removing this group on the first manual edit of the contact.

In this case, the roster group should be named by the client according to the user's locale settings. However, this approach might lead to different clients using different group names, resulting in multiple roster groups with the same goal.

7. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [8].

8. XMPP Registrar Considerations

Include the "urn:xmpp:pars:0" namespace in the registry of protocol namespaces. Include "preauth" as an additional key-value parameter to the roster query action.

New Roster Query Action Parameter
      <desc>the token used to obtain an automatic approval from the target JID</desc>

9. XML Schema

REQUIRED for protocol specifications.


Appendix A: Document Information

XMPP Standards Foundation
Standards Track
Last Updated
Approving Body
XMPP Council
XMPP Core, RFC 5122, XEP-0147
Superseded By
Short Name
Source Control

This document in other formats: XML  PDF

Appendix B: Author Information

Georg Lukas


This XMPP Extension Protocol is copyright © 1999 – 2024 by the XMPP Standards Foundation (XSF).


Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Given that this XMPP Extension Protocol normatively references IETF technologies, discussion on the <xsf-ietf@xmpp.org> list might also be appropriate.

Errata can be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

1. RFC 5122: Internationalized Resource Identifiers (IRIs) and Uniform Resource Identifiers (URIs) for the Extensible Messaging and Presence Protocol (XMPP) <http://tools.ietf.org/html/rfc5122>.

2. XEP-0147: XMPP URI Query Components <https://xmpp.org/extensions/xep-0147.html>.

3. XEP-0401: Easy User Onboarding <https://xmpp.org/extensions/xep-0401.html>.

4. See for example getrandom(2), SecureRandom or /dev/urandom. More information about the randomness requirements for security can be found in RFC 4086 [5]

5. RFC 4086: Randomness Requirements for Security <http://tools.ietf.org/html/rfc4086>.

6. Security Assertion Markup Language <http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security>.

7. RFC 7519: JSON Web Token (JWT) <http://tools.ietf.org/html/rfc7519>.

8. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

Appendix H: Revision History

Note: Older versions of this specification might be available at https://xmpp.org/extensions/attic/

  1. Version 0.3.3 (2021-03-04)

    Cross-document editorial adjustments for inclusive language.

  2. Version 0.3.2 (2020-01-14)
    Fix a bunch of typos.
  3. Version 0.3.1 (2018-11-03)
    Fix a bunch of typos, batch-style.
  4. Version 0.3.0 (2018-10-01)
    Defer due to lack of activity.
    XEP Editor (jsc)
  5. Version 0.2.0 (2017-03-06)

    Change URI format, editing, add reference to XEP-0401.

  6. Version 0.1.2 (2017-02-16)

    Added "Usability Considerations", removed actual XMPP client, some text editing.

  7. Version 0.1.1 (2017-01-01)

    Minor DTD and formatting fixes.

  8. Version 0.1.0 (2016-07-20)

    First draft.

    gl (XEP Editor: ssw)

Appendix I: Bib(La)TeX Entry

  title = {Pre-Authenticated Roster Subscription},
  author = {Lukas, Georg},
  type = {XEP},
  number = {0379},
  version = {0.3.3},
  institution = {XMPP Standards Foundation},
  url = {https://xmpp.org/extensions/xep-0379.html},
  date = {2016-07-20/2021-03-04},