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.

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.

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. This requires an additional mechanism to query the server for new (and possibly also for pending) invitation links.

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:

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

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 meta-data 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 meta-data 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.

A possible screen representation of the landing page would be:

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.

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

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

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

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.

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

Juliet's client SHOULD check the subscription request sender JID against the whitelist, and either automatically approve the request or display an according notification to Juliet.

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.

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.

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.

Some mobile device platforms allow an app to register itself as a handler for cetain URIs. This allows an XMPP client to register for xmpp: URIs, but also to redirect handling of cetain HTTP/HTTPS URIs. A mobile client SHOULD register for the associated landing page URIs and properly handle the contained invitations. For example, the yaxim client should register a handler for https://yax.im/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.

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 See for example getrandom(2), SecureRandom or /dev/urandom. More information about the randomness requirements for security can be found in &rfc4086; 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 SAMLSecurity Assertion Markup Language (SAML) <https://www.oasis-open.org/standards#samlv2.0> or JWT (RFC 7519RFC 7519: JSON Web Token (JWT) <http://tools.ietf.org/html/rfc7519>). In such a case, the issuer must ensure a comparable security level and limit token reuse.

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

• Usage: in the typical scenario, each token may only be used once. While it is possible for a client to generate a token for multiple uses (like for embedding it in a contact card), the conventional manual roster management should be used for public invitation links.
• Time: each token MUST have a limited validity time. As the token is transmitted out-of-band, it should provide sufficient reaction time, e.g. one week. This time limit also allows the issuer to delete expired tokens.
• Identity: if the JID of the token receiver is known in advance, the token sender MUST NOT allow a different JID to redeem this token.

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.

The invitation link that is generated by Romeo's client is considered a personal invitation link for a single person. This, and the fact that the link can only be used once, should be indicated by the client to Romeo.

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.

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.