The Jabber protocols have long included a method for in-band registration with instant messaging servers and associated services. This method makes use of the 'jabber:iq:register' namespace and has been documented variously in Internet-Drafts and elsewhere. Because in-band registration is not required by &rfc2779;, documentation of the 'jabber:iq:register' namespace was removed from &xmppim;. This specification fills the void for canonical documentation.

In-band registration must make it possible for an entity to register with a host, cancel an existing registration with a host, or change a password with a host. By "host" is meant either of the following:

1. an instant messaging server, such as described in XMPP IM and identified by the "server/im" &xep0030; category+type
2. an add-on service, such as a gateway (see &xep0100;) or a &xep0045; service

If needed, extensibility with regard to information gathered should be done using &xep0004;.

The fields defined for the 'jabber:iq:register' namespace are strictly limited to those specified in the schema. If a host needs to gather additional information, XEP-0004: Data Forms ("x:data") SHOULD be used according to the following rules:

1. A host MUST NOT add new fields to the 'jabber:iq:register' namespace; instead, extensibility SHOULD be pursued via the Data Forms protocol as specified herein.
2. The x:data form shall be contained as a child element of the <query xmlns='jabber:iq:register'/> element (it cannot be a child of the &IQ; stanza and comply with &rfc6120;).
3. The x:data form SHOULD contain x:data fields that correspond to all of the iq:register fields (e.g., username and password).
4. The x:data form SHOULD use a hidden FORM_TYPE field for the purpose of standardizing field names within the form, as defined in &xep0068;.
5. The x:data form shall take precedence over the iq:register fields; if the submitting entity supports the Data Forms protocol, it SHOULD submit the data form rather than the predefined 'jabber:iq:register' fields, and MUST NOT submit both the data form and the predefined fields (see the Precedence Order section of this document).

Support for extensibility via Data Forms is RECOMMENDED but is not required for compliance with this document.

A given deployment MAY wish to redirect users to another medium (e.g., a website) for registration, rather than allowing in-band registration. The recommended approach is to include only the <instructions/> element rather than the required fields or a data form in the IQ result, as well as a URL encoded using &xep0066; (see the Precedence Order section below for further details).

Given the foregoing discussion, it is evident that an entity could receive any combination of iq:register, x:data, and x:oob namespaces from a service in response to a request for information. The precedence order is as follows:

1. x:data
2. iq:register
3. x:oob

(Naturally, if the receiving application does not understand any of the foregoing namespaces, it MUST ignore the data qualified by that namespace.)

Thus it is possible that the host may return any of the following combinations, in which case the submitting application MUST proceed as defined in the table below (it is assumed that "iq:register fields" means instructions plus fields, whereas "iq:register instructions" means the <instructions/> element only):

This element is obsolete, but is documented here for historical completeness.

The <key/> element was used as a "transaction key" in certain IQ interactions in order to verify the identity of the sender. In particular, it was used by servers (but generally not services) during in-band registration, since normally a user does not yet have a 'from' address before registering. The flow is as follows:

1. Client sends IQ-get request to server.
2. Server returns required elements to client, including <key/> element containing a random string (often a SHA-1 hash).
3. Client sends registration information to server, including <key/> element with the same value provided by the server.
4. Server checks key information and processes registration request; if key is missing or the key value does not match the transaction key provided, the server returns an error.

The <key/> element was also used during registration removal.

RFC 6120 defines methods for advertising feature support during stream negotiation. For the sake of efficiency, it may be desirable for a server to advertise support for in-band registration as a stream feature. The namespace for reporting support within <stream:features/> is "http://jabber.org/features/iq-register". Upon receiving a stream header qualified by the 'jabber:client' namespace, a server returns a stream header to the client and MAY announce support for in-band registration by including the relevant stream feature:

A server SHOULD NOT advertise in-band registration to another server (i.e., if the initial stream header was qualified by the 'jabber:server' namespace).

As defined herein, the 'jabber:iq:register' namespace supports both the old (HTTP-style) error codes and the extensible error classes and conditions specified in XMPP Core. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both. For mappings of HTTP-style errors to XMPP-style conditions, refer to &xep0086;.

If an entity supports the protocol defined herein, it SHOULD report that by including a Service Discovery feature of "jabber:iq:register" in response to disco#info requests.

Although connecting clients typically determine support during stream negotiation via the stream feature, the service discovery feature is helpful for server-to-server connections as well as for clients that are already connected (e.g., to determine if password changes are possible in-band).

In-band registration is usually not included in other messaging protocols (for example, SMTP does not include a method for registering with an email server), often for reasons of security. The registration methods defined herein are known to be insecure and SHOULD NOT be used unless the channel between the registrant and the entity that accepts registration has been secured. For these reasons, the deployment of in-band registration is a policy matter and a given deployment MAY choose to disable in-band registration and password changes. Furthermore, this document should be deprecated as soon as a successor protocol is defined and implemented.

This document requires no interaction with &IANA;.