<abstract>This specification documents a protocol for in-band registration with instant messaging servers and associated services using the jabber:iq:register namespace.</abstract>
<remark><p>Further specified integration with data forms, specifically if needed to require additional information when cancelling an existing registration (e.g., username and password) or changing a password (e.g., old password); also clarified server handling of cancelled registrations.</p></remark>
<remark><p>Clarified the extensibility rules; removed expiration date; modified schema to document optional inclusion of jabber:x:data and jabber:x:oob information.</p></remark>
<remark><p>Per a vote of the Jabber Council, advanced status to Final; also specified that by server is meant an instant messaging server.</p></remark>
<remark><p>In order to address Council concerns, clarified precedence order of x:data, iq:register, and x:oob; further specified server handling of initial registration requests from unregistered entities.</p></remark>
<remark><p>Restored the <misc/> and <text/> elements; added the old <key/> element; specified these three elements as obsolete.</p></remark>
<remark><p>Added <registered/> element; specified FORM_TYPE for x:data form; clarified that support for the extensibility mechanism is optional; removed the <misc/> and <text/> elements (not necessary given extensibility option); added <nick/>, <first/>, and <last/> elements that were traditionally documented as part of jabber:iq:register.</p></remark>
<p>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.</p>
<p>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:</p>
<section2topic='Entity Registers with a Host'anchor='usecases-register'>
<p>In order to determine which fields are required for registration with a host, an entity SHOULD first send an IQ get to the host. The entity SHOULD NOT attempt to guess at the required fields by first sending an IQ set, since the nature of the required data is subject to service provisioning.</p>
<examplecaption='Entity Requests Registration Fields from Host'><![CDATA[
<iqtype='get'id='reg1'>
<queryxmlns='jabber:iq:register'/>
</iq>
]]></example>
<p>If the entity is not already registered and the host supports In-Band Registration, the host MUST inform the entity of the required registration fields. If the host does not support In-Band Registration, it MUST return a &unavailable; error. If the host is redirecting registration requests to some other medium (e.g., a website), it MAY return an <instructions/> element only, as shown in the <linkurl="#redirect">Redirection</link> section of this document.</p>
<examplecaption='Host Returns Registration Fields to Entity'><![CDATA[
<iqtype='result'id='reg1'>
<queryxmlns='jabber:iq:register'>
<instructions>
Choose a username and password for use with this service.
Please also provide your email address.
</instructions>
<username/>
<password/>
<email/>
</query>
</iq>
]]></example>
<p>If the host determines (based on the 'from' address) that the entity is already registered, the IQ result that it sends in response to the IQ get MUST contain an empty <registered/> element (indicating that the entity is already registered), SHOULD contain the registration information currently on file for the entity (although the <password/> element MAY be empty), and SHOULD contain an <instructions/> element (whose XML character data MAY be modified to reflect the fact that the entity is currently registered).</p>
<p>If the host is an instant messaging server, it SHOULD assume that the requesting entity is unregistered at this stage unless the entity has already authenticated (for details, see the <linkurl="#usecases-register-server">Registration with a Server</link> section below).</p>
<examplecaption='Host Informs Entity of Current Registration'><![CDATA[
<iqtype='result'id='reg1'>
<queryxmlns='jabber:iq:register'>
<registered/>
<username>juliet</username>
<password>R0m30</password>
<email>juliet@capulet.com</email>
</query>
</iq>
]]></example>
<p>If the entity is not already registered, the entity SHOULD provide the required information.</p>
<p>Note: The requesting entity MUST provide information for all of the elements (other than <instructions/>) contained in the IQ result.</p>
<examplecaption='Host Informs Entity of Successful Registration'><![CDATA[
<iqtype='result'id='reg2'/>
]]></example>
<p>Alternatively, registration may fail. Possible causes of failure include a username conflict (the desired username is already in use by another entity) and the fact that the requesting entity neglected to provide all of the required information.</p>
<examplecaption='Host Informs Entity of Failed Registration (Username Conflict)'><![CDATA[
<p>If the requesting entity does not provide all of the requested information during registration <note>This includes providing an empty password element or a password element that contains no XML character data, i.e., either <password/> or <password></password>.</note> then the server or service MUST return a ¬acceptable; error to the requesting entity.</p>
<examplecaption='Host Informs Entity of Failed Registration (Some Required Information Not Provided)'><![CDATA[
<p>If the host requires additional information above and beyond the data elements specified in the schema, it SHOULD use Data Forms as described in the <linkurl='#extensibility'>Extensibility</link> section of this document.</p>
<examplecaption='Entity Requests Registration Fields from Host'><![CDATA[
<iqtype='get'
from='juliet@capulet.com/balcony'
to='contests.shakespeare.lit'
id='reg3'>
<queryxmlns='jabber:iq:register'/>
</iq>
]]></example>
<examplecaption='Host Returns Registration Form to Entity'><![CDATA[
<iqtype='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg3'>
<queryxmlns='jabber:iq:register'>
<instructions>
Use the enclosed form to register. If your Jabber client does not
support Data Forms, visit http://www.shakespeare.lit/contests.php
<section3topic='Registration with a Server'anchor='usecases-register-server'>
<p>Special care must be taken when an unregistered entity interacts with a server rather than a service. Normally, a server enables in-band registration so that entities can "bootstrap" their participation in the Jabber network; this bootstrapping happens when an unregistered and unauthenticated entity opens a TCP connection to a server and immediately completes the registration use case with the server, then authenticates using the newly-registered identity. As noted, when a server receives an IQ-get for registration information, it SHOULD assume that the requesting entity is unregistered unless the entity has already authenticated.</p>
<p>Depending on local service provisioning, a server MAY return a ¬acceptable; stanza error if an unregistered entity attempts to register too many times before authenticating or if an entity attempts to register a second identity after successfully completing the registration use case; a server MAY also return a <not-authorized/> stream error if the unregistered entity waits too long before authenticating or attempts to complete a task other than authentication after successfully completing the registration use case.</p>
</section3>
</section2>
<section2topic='Entity Cancels an Existing Registration'anchor='usecases-cancel'>
<p>The 'jabber:iq:register' namespace also makes it possible for an entity to cancel a registration with a host by sending a <remove/> element in an IQ set. The host MUST determine the identity of the requesting entity based on the 'from' address of the IQ get.</p>
<examplecaption='Entity Requests Cancellation of Existing Registration'><![CDATA[
<li><p>If the entity cancels its registration with its "home" server (i.e., the server at which it has maintained its XMPP account), then the entity SHOULD NOT include a 'from' or 'to' address in the remove request the server SHOULD then return a <not-authorized/> stream error and terminate all active sessions for the entity. The server SHOULD perform the remove based on the bare JID (&BAREJID;) associated with the current session or connection over which it received the remove request. If the server is an instant messaging and presence server that conforms to &rfc3921;, the server SHOULD also cancel all existing presence subscriptions related to that entity (as stored in the entity's roster).</p></li>
<li><p>If the entity cancels its registration with a service other than its home server, its home server MUST stamp a 'from' address on the remove request, which in accordance with <cite>XMPP Core</cite> will be the entity's full JID (&FULLJID;). The service MUST perform the remove based on the bare JID (&BAREJID;) portion of the 'from' address.</p></li>
</ol>
<p>As specified below, several error cases are possible.</p>
<tr><td>&badrequest;</td><td>The <remove/> element was not the only child element of the <query/> element.</td></tr>
<tr><td>&forbidden;</td><td>The sender does not have sufficient permissions to cancel the registration.</td></tr>
<tr><td>¬allowed;</td><td>No sender is allowed to cancel registrations in-band.</td></tr>
<tr><td>®istration;</td><td>The entity sending the remove request was not previously registered.</td></tr>
<tr><td>&unexpected;</td><td>The host is an instant messaging server and the IQ get does not contain a 'from' address because the entity is not registered with the server.</td></tr>
</table>
<examplecaption='Host Informs Client of Failed Cancellation (Bad Request)'><![CDATA[
<p>A given deployment MAY choose to require additional information (such as the old password or previously-gathered personal information) before cancelling the registration. In order to do so, the server or service SHOULD return a Data Form in the error stanza:</p>
<examplecaption='Server Returns Cancellation Form With Error'><![CDATA[
<p>The 'jabber:iq:register' namespace enables a user to change his or her password with a server or service. Once registered, the user can change passwords by sending an XML stanza of the following form:</p>
<examplecaption='Password Change'><![CDATA[
<iqtype='set'to='shakespeare.lit'id='change1'>
<queryxmlns='jabber:iq:register'>
<username>bill</username>
<password>newpass</password>
</query>
</iq>
]]></example>
<p>Because the password change request contains the password in plain text, a client SHOULD NOT send such a request unless the underlying stream is encrypted (using SSL or TLS) and the client has verified that the server certificate is signed by a trusted certificate authority. A given deployment MAY choose to disable password changes if the stream is not properly encrypted, to disable in-band password changes, or to require additional information (such as the old password or previously-gathered personal information) before changing the password.</p>
<p>If the user provides an empty password element or a password element that contains no XML character data (i.e., either <password/> or <password></password>), the server or service MUST NOT change the password to a null value, but instead MUST maintain the existing password.</p>
<examplecaption='Host Informs Client of Successful Password Change'><![CDATA[
<iqtype='result'id='change1'/>
]]></example>
<p>Several error conditions are possible:</p>
<tablecaption='Password Change Error Cases'>
<tr><th>Condition</th><th>Description</th></tr>
<tr><td>&badrequest;</td><td>The password change request does not contain complete information (both <username/> and <password/> are required).</td></tr>
<tr><td>¬authorized;</td><td>The server or service does not consider the channel safe enough to enable a password change.</td></tr>
<tr><td>¬allowed;</td><td>The server or service does not allow password changes.</td></tr>
<tr><td>&unexpected;</td><td>The host is an instant messaging server and the IQ set does not contain a 'from' address because the entity is not registered with the server.</td></tr>
</table>
<p>The server or service SHOULD NOT return the original XML sent in IQ error stanzas related to password changes.</p>
<examplecaption='Host Informs Client of Failed Password Change (Bad Request)'><