This JEP documents a protocol for in-band registration with instant messaging servers and associated services using the jabber:iq:register namespace.
NOTICE: The protocol defined herein is a Final Standard of the Jabber Software Foundation and may be considered a stable technology for implementation and deployment.
Status: Final
Type: Standards Track
Number: 0077
Version: 2.0
Last Updated: 2004-08-30
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: iq-register
Schema: <http://jabber.org/protocol/iq-register/iq-register.xsd>
Email: stpeter@jabber.org
JID: stpeter@jabber.org
This Jabber Enhancement Proposal is copyright 1999 - 2005 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software 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 JEP 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.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
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 RFC 2779 [1], documentation of the 'jabber:iq:register' namespace was removed from XMPP IM [2]. This JEP fills the void for canonical documentation.
In-band registration must make it possible for an entity to register with a host, or cancel an existing registration with a host. By "host" is meant either of the following:
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.
Example 1. Entity Requests Registration Fields from Host
<iq type='get' id='reg1'>
<query xmlns='jabber:iq:register'/>
</iq>
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 <service-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 Redirection section of this document.
Example 2. Host Returns Registration Fields to Entity
<iq type='result' id='reg1'>
<query xmlns='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>
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).
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 Registration with a Server section below).
Example 3. Host Informs Entity of Current Registration
<iq type='result' id='reg1'>
<query xmlns='jabber:iq:register'>
<registered/>
<username>juliet</username>
<password>R0m30</password>
<email>juliet@capulet.com</email>
</query>
</iq>
If the entity is not already registered, the entity SHOULD provide the required information.
Example 4. Entity Provides Required Information
<iq type='set' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>Calliope</password>
<email>bill@shakespeare.lit</email>
</query>
</iq>
Note: The requesting entity MUST provide information for all of the elements (other than <instructions/>) contained in the IQ result.
If the requesting entity provides an empty password element or a password element that contains no XML character data (i.e., either <password/> or <password></password>) during initial registration, the server or service MUST return a "Not Acceptable" error to the requesting entity.
Example 5. Host Informs Entity of Successful Registration
<iq type='result' id='reg2'/>
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.
Example 6. Host Informs Entity of Failed Registration (Username Conflict)
<iq type='error' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>m1cro$oft</password>
<email>billg@bigcompany.com</email>
</query>
<error code='409' type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Example 7. Host Informs Entity of Failed Registration (Some Required Information Not Provided)
<iq type='error' id='reg2'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>Calliope</password>
</query>
<error code='406' type='modify'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
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.
Depending on local service provisioning, a server MAY return a <not-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.
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.
Example 8. Entity Requests Cancellation of Existing Registration
<iq type='set' from='bill@shakespeare.lit/globe' id='unreg1'>
<query xmlns='jabber:iq:register'>
<remove/>
</query>
</iq>
Example 9. Host Informs Entity of Successful Cancellation
<iq type='result' to='bill@shakespeare.lit/globe' id='unreg_1'/>
The host MUST perform the remove based on the 'from' address of the IQ set, usually matching based on bare JID (user@domain).
Several error cases are possible:
Table 1: Unregister Error Cases
| Condition | Description |
|---|---|
| <bad-request/> | The <remove/> element was not the only child element of the <query/> element. |
| <forbidden/> | The sender does not have sufficient permissions to cancel the registration. |
| <registration-required/> | The entity sending the remove request was not previously registered. |
| <unexpected-request/> | 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. |
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 (where 'somehost' is the domain identifier of the server or service):
Example 10. Password Change
<iq type='set' to='somehost' id='change1'>
<query xmlns='jabber:iq:register'>
<username>bill</username>
<password>newpass</password>
</query>
</iq>
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 domain MAY choose to disable password changes if the stream is not properly encrypted, or to disable in-band password changes entirely.
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.
Example 11. Host Informs Client of Successful Password Change
<iq type='result' id='change1'/>
Several error conditions are possible:
Table 2: Password Change Error Cases
| Condition | Description |
|---|---|
| <bad-request/> | The password change request does not contain complete information (both <username/> and <password/> are required). |
| <not-authorized/> | The server or service does not consider the channel safe enough to enable a password change. |
| <not-allowed/> | The server or service does not allow password changes. |
| <unexpected-request/> | 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. |
The server or service SHOULD NOT return the original XML sent in IQ error stanzas related to password changes.
Example 12. Host Informs Client of Failed Password Change (Bad Request)
<iq type='error' from='somehost' to='user@host/resource' id='change1'>
<error code='400' type='modify'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Example 13. Host Informs Client of Failed Password Change (Not Authorized)
<iq type='error' from='somehost' to='user@host/resource' id='change1'>
<error code='401' type='cancel'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
Example 14. Server Informs Client of Failed Password Change (Not Allowed)
<iq type='error' from='somehost' to='user@host/resource' id='change1'>
<error code='405' type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
The fields defined in the 'jabber:iq:register' namespace are strictly limited to those specified in the schema. If a host needs to gather additional information, Data Forms [6] SHOULD be used, with the x:data form taking precedence over the iq:register fields (see the Precedence Order section below for further details); a host MUST NOT add new fields to the 'jabber:iq:register' namespace. Support for extensibility via jabber:x:data is RECOMMENDED but is not required for compliance with this JEP.
If the 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.
The extensibility mechanism for registration makes use of a hidden FORM_TYPE field for the purpose of standardizing field names within the form, as defined in Field Standardization for Data Forms [7]. Implementations supporting this extensibility mechanism SHOULD support the standardized fields as well.
Example 15. Entity Requests Registration Fields from Host
<iq type='get'
from='juliet@capulet.com/balcony'
to='contests.shakespeare.lit'
id='reg3'>
<query xmlns='jabber:iq:register'/>
</iq>
Example 16. Host Returns Registration Form to Entity
<iq type='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg3'>
<query xmlns='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
</instructions>
<x xmlns='jabber:x:data' type='form'>
<title>Contest Registration</title>
<instructions>
Please provide the following information
to sign up for our special contests!
</instructions>
<field
type='hidden'
var='FORM_TYPE'>
<value>jabber:iq:register</value>
</field>
<field
type='text-single'
label='Given Name'
var='first'>
<required/>
</field>
<field
type='text-single'
label='Family Name'
var='last'>
<required/>
</field>
<field
type='text-single'
label='Email Address'
var='email'>
<required/>
</field>
<field
type='list-single'
label='Gender'
var='x-gender'>
<option label='Male'><value>M</value></option>
<option label='Female'><value>F</value></option>
</field>
</x>
</query>
</iq>
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 Out-of-Band Data [8] (see the Precedence Order section below for further details).
Example 17. Host Redirects Entity to Web Registration
<iq type='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg3'>
<query xmlns='jabber:iq:register'>
<instructions>
To register, visit http://www.shakespeare.lit/contests.php
</instructions>
</query>
<x xmlns='jabber:x:oob'>
<url>http://www.shakespeare.lit/contests.php</url>
</x>
</iq>
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:
(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):
Table 3: Recommended Processing of Namespace Combinations
| Included Data | Recommended Processing | Notes |
|---|---|---|
| iq:register fields | Submit the completed iq:register fields. | This is the normal processing model for "legacy" services and clients. |
| x:data form + iq:register fields | Submit the completed x:data form if understood, otherwise submit the completed iq:register fields; however, an application MUST NOT submit both. | The iq:register fields would be included for "legacy" clients; this combination SHOULD NOT be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields (the next combination SHOULD be used instead). |
| x:data form + iq:register instructions | Submit the completed x:data form if understood, otherwise present the iq:register instructions to the user. | This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is not available. |
| x:data form + x:oob URL | Submit the completed x:data form if understood, otherwise present the provided URL as an alternative. | This combination MAY be returned by a host, but a host SHOULD return the next combination instead in order to support the full range of legacy clients. |
| x:data form + iq:register instructions + x:oob URL | Submit the completed x:data form if understood, otherwise present the iq:register instructions and provided URL as an alternative. | This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is available. |
| iq:register instructions + x:oob URL | Present the iq:register instructions and provided URL as a redirect. | This combination MAY be returned by a host that wishes to redirect registration to a URL. |
| iq:register fields + x:oob URL | Submit the completed iq:register fields but optionally present the provided URL as an alternative. | This combination is NOT RECOMMENDED. |
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:
The <key/> element was also used during registration removal.
XMPP Core [9] 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:
Example 18. Advertising registration as a stream feature
<?xml version='1.0' encoding='utf-8'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams/'
xmlns='jabber:client'
from='somedomain'
version='1.0'>
<stream:features>
...
<register xmlns='http://jabber.org/features/iq-register'/>
...
</stream:features>
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 Error Condition Mappings [10].
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 domain MAY choose to disable in-band registration and password changes. Furthermore, this JEP should be deprecated as soon as a successor protocol is defined and implemented.
In accordance with Section 8 of Jabber Enhancement Proposals [11], this JEP shall expire 6 months from the date of its advancement to a status of Final. The Jabber Council shall review this JEP before its expiration date, and at that time shall determine whether to change its status to Deprecated or to extend the expiration date for an additional six months. That process will continue until the JEP is deprecated or made a permanent standard.
This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [12].
The Jabber Registrar [13] includes the 'jabber:iq:register' namespace in its registry of protocol namespaces.
The Jabber Registrar includes the 'http://jabber.org/features/iq-register' namespace in its registry of stream feature namespaces.
As described in the Extensibility section above, this proposal includes registration of a FORM_TYPE and associated field types and names for field standardization as defined in JEP-0068. The initial submission is as follows (additional fields may be provided in future submissions):
<form_type>
<name>jabber:iq:register</name>
<doc>JEP-0077</doc>
<desc>
Standardization of fields related to in-band registration.
</desc>
<field
var='username'
type='text-single'
label='Account name associated with the user'/>
<field
var='nick'
type='text-single'
label='Familiar name of the user'/>
<field
var='password'
type='text-private'
label='Password or secret for the user'/>
<field
var='name'
type='text-single'
label='Full name of the user'/>
<field
var='first'
type='text-single'
label='First name or given name of the user'/>
<field
var='last'
type='text-single'
label='Last name, surname, or family name of the user'/>
<field
var='email'
type='text-single'
label='Email address of the user'/>
<field
var='address'
type='text-single'
label='Street portion of a physical or mailing address'/>
<field
var='city'
type='text-single'
label='Locality portion of a physical or mailing address'/>
<field
var='state'
type='text-single'
label='Region portion of a physical or mailing address'/>
<field
var='zip'
type='text-single'
label='Postal code portion of a physical or mailing address'/>
<field
var='phone'
type='text-single'
label='Telephone number of the user'/>
<field
var='url'
type='text-single'
label='URL to web page describing the user'/>
<field
var='date'
type='text-single'
label='Some date (e.g., birth date, hire date, sign-up date)'/>
<field
var='misc'
type='text-single'
label='Free-form text field (obsolete)'/>
<field
var='text'
type='text-single'
label='Free-form text field (obsolete)'/>
<field
var='key'
type='text-single'
label='Session key for transaction (obsolete)'/>
</form_type>
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:iq:register'
xmlns='jabber:iq:register'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0077: http://www.jabber.org/jeps/jep-0077.html
</xs:documentation>
</xs:annotation>
<xs:element name='query'>
<xs:complexType>
<xs:choice>
<xs:sequence minOccurs='0'>
<xs:element name='registered' type='empty' minOccurs='0'/>
<xs:element name='instructions' type='xs:string' minOccurs='0'/>
<xs:element name='username' type='xs:string' minOccurs='0'/>
<xs:element name='nick' type='xs:string' minOccurs='0'/>
<xs:element name='password' type='xs:string' minOccurs='0'/>
<xs:element name='name' type='xs:string' minOccurs='0'/>
<xs:element name='first' type='xs:string' minOccurs='0'/>
<xs:element name='last' type='xs:string' minOccurs='0'/>
<xs:element name='email' type='xs:string' minOccurs='0'/>
<xs:element name='address' type='xs:string' minOccurs='0'/>
<xs:element name='city' type='xs:string' minOccurs='0'/>
<xs:element name='state' type='xs:string' minOccurs='0'/>
<xs:element name='zip' type='xs:string' minOccurs='0'/>
<xs:element name='phone' type='xs:string' minOccurs='0'/>
<xs:element name='url' type='xs:string' minOccurs='0'/>
<xs:element name='date' type='xs:string' minOccurs='0'/>
<xs:element name='misc' type='xs:string' minOccurs='0'/>
<xs:element name='text' type='xs:string' minOccurs='0'/>
<xs:element name='key' type='xs:string' minOccurs='0'/>
</xs:sequence>
<xs:element name='remove' type='empty' minOccurs='0'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://jabber.org/features/iq-register'
xmlns='http://jabber.org/features/iq-register'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
JEP-0077: http://www.jabber.org/jeps/jep-0077.html
</xs:documentation>
</xs:annotation>
<xs:element name='register' type='empty'/>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
1. RFC 2779: A Model for Presence and Instant Messaging <http://www.ietf.org/rfc/rfc2779.txt>.
2. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.
3. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.
4. JEP-0100: Gateway Interaction <http://www.jabber.org/jeps/jep-0100.html>.
5. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.
6. JEP-0004: Data Forms <http://www.jabber.org/jeps/jep-0004.html>.
7. JEP-0068: Field Data Standardization for Data Forms <http://www.jabber.org/jeps/jep-0068.html>.
8. JEP-0066: Out of Band Data <http://www.jabber.org/jeps/jep-0066.html>.
9. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.
10. JEP-0086: Error Condition Mappings <http://www.jabber.org/jeps/jep-0086.html>.
11. JEP-0001: Jabber Enhancement Proposals <http://www.jabber.org/jeps/jep-0001.html>.
12. 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/>.
13. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.
END