Modern Login Procedure

Jump to: navigation, search

This page aims at documenting the XMPP login procedure for a modern client, desktop or mobile, providing a good user experience.

This page is currently in progress and not final.

Feel free to provide feedback in the XSF MUC or directly at


Discovery of connection endpoints

Starting with user provided JID and login credentials like password or certificate, before starting a XMPP connection a suitable connection endpoint needs to be found.

The primary way of discovery is via lookup of DNS SRV records. DNS SRV records provide a flexible way of controlling multiple connection endpoints, including weights and priorities.

Over the years more discovery methods have been suggested:

  1. XEP-0156: Discovering Alternative XMPP Connection Methods, providing discovery of BOSH and XMPP over WebSockets via DNS TXT or HTTP lookups.
  2. XEP-0368: SRV records for XMPP over TLS, allowing direct TLS connection to an endpoint without STARTTLS.


It is generally recommended to require a connection endpoint that provides transport security like TLS over TCP or HTTPS in case of BOSH. Considering this requirement, one would have the fastest secure connection establishment via XEP-0368 SRV records for direct TLS as standard TLS via the STARTTLS mechanism comes with additional in-band discovery and establishment round trips.

BOSH and WebSocket connectivity endpoints are important for successful connection in more network constrained environments, e.g. behind firewalls and HTTP proxies.

Clients may want to implement a connection procedure similar to Happy Eyeballs where they try to connect to similar qualified connection endpoints. Direct TLS via XEP-0368 should be given an advantage as even a slightly slower initial connection establishment can save time later by reducing roundtrips. Furthermore SRV record weights and priorities have to be correctly considered, as clients should try higher numbered priority endpoints only after the lower numbered priority endpoints failed.

Establishing a secure connection to the endpoint

If the client choose a standard XMPP TCP endpoint via SRV records, then it'll need to start a XMPP XML stream to the server, detect support for STARTTLS and initiate the STARTTLS handshake. If STARTTLS is not supported the whole connection attempt should be aborted.

If the client choose a XEP-0368 TLS SRV record, then it can directly start the TLS connection to the endpoint.

User authentication (SASL)

Stream resumption (XEP-0198) (continue old stream)

Session binding (new stream)