This specification defines an XMPP extension for generating, requesting, and using authorization tokens, which can be used to join Multi-User Chat rooms, subscribe to Publish-Subscribe nodes, and even register XMPP accounts.
WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Series: XEP
Number: 0235
Publisher: XMPP Standards Foundation
Status:
Experimental
Type:
Standards Track
Version: 0.3
Last Updated: 2008-03-31
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT YET ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Authorization Tokens (XEP-0235)>
JabberID:
stpeter@jabber.org
URI:
https://stpeter.im/
The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.
Errata may be sent to <editor@xmpp.org>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards 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 document 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 following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. Introduction
2. Obtaining an Authorization Token
3. Generating an Authorization Token
4. Sharing an Authorization Token
5. Using an Authorization Token
5.1. Multi-User Chat
5.2. Publish-Subscribe
5.3. Account Registration
6. Determining Support
7. Security Considerations
8. IANA Considerations
9. XMPP Registrar Considerations
9.1. Protocol Namespaces
9.2. Field Standardization
9.2.1. jabber:iq:register
10. XML Schema
11. Acknowledgements
Notes
Revision History
Although authentication is required in order to access an XMPP network, in some situations it is desirable to require authorization in order to access certain entities on the network. For example, authorization may be required in order to join a Multi-User Chat [1] room or to subscribe to a Publish-Subscribe [2] node. This document defines a general method for obtaining, sharing, and using authorization tokens over XMPP.
In order to obtain an authorization token that can be sent to a consumer, a user requests an authorization token from the relevant service. For example, let us imagine that the user <crone1@shakespeare.lit> wishes to invite the consumer <hecate@shakespeare.lit> to the chatroom <darkcave@macbeth.shakespeare.lit>. Assuming that the user has already determined that the chatroom supports authorization tokens, the user would send the following request to the room (see Protocol Namespaces regarding issuance of one or more permanent namespaces).
<iq from='crone1@shakespeare.lit/desktop'
id='request1'
to='darkcave@macbeth.shakespeare.lit'
type='get'>
<token xmlns='urn:xmpp:tmp:auth-token'
consumer='xmpp:hecate@shakespeare.lit'/>
</iq>
If the room supports authorization tokens and the user is allowed to invite contacts to the room, the room returns an authorization token to the user.
<iq from='darkcave@macbeth.shakespeare.lit'
id='request1'
to='crone1@shakespeare.lit/desktop'
type='result'>
<token xmlns='urn:xmpp:tmp:auth-token'
consumer='xmpp:hecate@shakespeare.lit'
expires='2007-02-21T23:59:59Z'
service='darkcave@macbeth.shakespeare.lit'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</token>
</iq>
The syntax of the <token/> element is as follows.
A service MAY use any algorithm in generating an authorization token. Depending on implementation and deployment policies, the algorithm MAY take into account the URI of the consumer and be limited to use by an entity that communicates via that URI. Acceptable algorithms MAY include those defined by other standards development organizations, such as OAuth [4].
The user can then send the authorization token to the consumer in an XMPP message stanza:
Example 3. Sharing the authorization token
<message from='crone1@shakespeare.lit/desktop' to='hecate@shakespeare.lit'>
<token xmlns='urn:xmpp:tmp:auth-token'
consumer='xmpp:hecate@shakespeare.lit'
expires='2007-02-21T23:59:59Z'
service='darkcave@macbeth.shakespeare.lit'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</token>
</message>
If the consumer wishes to use the token, it MUST first determine the identity of the service (via Service Discovery [5]) so that it can decide how to proceed.
Note: If the service supports this protocol, it MUST return a service discovery feature of "urn:xmpp:tmp:auth-token" in response to each disco#info request (see the Determining Support section of this document).
In this example, the service is a multi-user chat service. If authorization is required in order to join a particular room but the joining entity does not include an authorization token in its join request, the service MUST return an error as follows.
Example 4. Chatroom join without token
<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'/>
Example 5. Error from chatroom
<presence from='darkcave@macbeth.shakespeare.lit/Hecate'
to='hecate@shakespeare.lit/broom'
type='error'>
<error type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<token-required xmlns='urn:xmpp:tmp:auth-token'/>
</error>
</presence>
The consumer would then include the authorization token in its join request.
Example 6. Chatroom join with token
<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'>
<token xmlns='urn:xmpp:tmp:auth-token'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</token>
</presence>
If the token is acceptable, the service will then allow the consumer to enter the room.
Note: Although XEP-0045 includes a protocol for inviting a contact to a chatroom, that protocol results in the sending of an invitation from the chatroom to the contact (a "mediated invitation"), not from the inviting user to the contact (a "direct invitation"). Because use of Server-Based Privacy Rules [6] may result in blocking of XML stanzas from entities that are not in the contact's roster, mediated invitations may never be delivered to the contact. Use of authorization tokens as described herein enables a user to directly send an invitation to a contact, thus routing around the blocking of mediated invitations.
In this example, the service is a publish-subscribe service. If authorization is required in order to subscribe to a particular node but the subscribing entity does not include an authorization token in its subscribe request, the service MUST return an error as follows.
Example 7. Subscription request without token
<iq type='set'
from='notify.marlowe.lit'
to='pubsub.shakespeare.lit'
id='sub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='bard_geoloc'/>
</pubsub>
</iq>
<iq type='error'
from='pubsub.shakespeare.lit'
to='notify.marlowe.lit'
id='sub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='bard_geoloc'/>
</pubsub>
<error type='auth'>
<not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<token-required xmlns='urn:xmpp:tmp:auth-token'/>
</error>
</iq>
The contact would then include the authorization token in its subscription request.
Example 9. Subscription request with token
<iq type='set'
from='notify.marlowe.lit'
to='pubsub.shakespeare.lit'
id='sub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='bard_geoloc'/>
<token xmlns='urn:xmpp:tmp:auth-token'>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</token>
</pubsub>
</iq>
If the token is acceptable, the service will then allow the consumer to subscribe to the node.
In this example, the service allows new account registration using In-Band Registration [7]. The registering entity SHOULD request the registration form before attempting to register.
Example 10. Consumer requests registration form
<iq type='get'
to='contests.shakespeare.lit'
id='reg1'>
<query xmlns='jabber:iq:register'/>
</iq>
Example 11. Host returns registration form
<iq type='result'
from='contests.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='reg1'>
<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>
<field type='text-single' label='Invitation Token' var='auth-token'>
<required/>
</field>
</x>
</query>
</iq>
The user then SHOULD return the form:
Example 12. User Submits Registration Form
<iq type='set'
from='juliet@capulet.com/balcony'
to='contests.shakespeare.lit'
id='reg2'>
<query xmlns='jabber:iq:register'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:iq:register</value>
</field>
<field type='text-single' label='Given Name' var='first'>
<value>Juliet</value>
</field>
<field type='text-single' label='Family Name' var='last'>
<value>Capulet</value>
</field>
<field type='text-single' label='Email Address' var='email'>
<value>juliet@capulet.com</value>
</field>
<field type='list-single' label='Gender' var='x-gender'>
<value>F</value>
</field>
<field var='auth-token'>
<value>
37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
</value>
</field>
</x>
</query>
</iq>
If the token is acceptable, the service will then allow the consumer to register.
If a service provides and accepts authorization tokens, it MUST advertise support for the 'urn:xmpp:tmp:auth-token' namespace in its disco#info replies (if provided) its Entity Capabilities [8] notations (see Protocol Namespaces regarding issuance of one or more permanent namespaces).
To follow.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [9].
Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:auth-token"; upon advancement of this specification, the XMPP Registrar [10] shall issue a permanent namespace in accordance with the process defined in Section 4 of XMPP Registrar Function [11].
This specification adds one field to the existing FORM_TYPE for In-Band Registration.
<form_type>
<name>jabber:iq:register</name>
<field
var='auth-token'
type='text-single'
label='Authorization token'/>
</form_type>
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:tmp:auth-token'
xmlns='urn:xmpp:tmp:auth-token'
elementFormDefault='qualified'>
<xs:import
namespace='jabber:x:data'
schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>
<xs:element name='token'>
<xs:complexType>
<xs:simpleContent>
<xs:extension base='xs:string'>
<xs:attribute name='consumer' type='xs:string' use='optional'/>
<xs:attribute name='expires' type='xs:string' use='optional'/>
<xs:attribute name='node' type='xs:string' use='optional'/>
<xs:attribute name='service' type='xs:string' use='optional'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name='token-required'>
<xs:complexType>
<xs:choice xmlns:xdata='jabber:x:data' minOccurs='0' maxOccurs='1'>
<xs:element ref='xdata:x'/>
</xs:choice>
</xs:complexType>
</xs:element>
</xs:schema>
Thanks to Dave Cridland and Pedro Melo for their suggestions. Aspects of this specification were inspired by RFC 4467 [12]. Some of the terminology in this specification was borrowed from OAuth.
1. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.
2. XEP-0060: Publish-Subscribe <http://www.xmpp.org/extensions/xep-0060.html>.
3. XEP-0082: XMPP Date and Time Profiles <http://www.xmpp.org/extensions/xep-0082.html>.
4. OAuth Core 1.0 <http://oauth.net/core/1.0/>.
5. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.
6. XEP-0016: Server-Based Privacy Rules <http://www.xmpp.org/extensions/xep-0016.html>.
7. XEP-0077: In-Band Registration <http://www.xmpp.org/extensions/xep-0077.html>.
8. XEP-0115: Entity Capabilities <http://www.xmpp.org/extensions/xep-0115.html>.
9. 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/>.
10. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.
11. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.
12. RFC 4467: Internet Message Access Protocol (IMAP) - URLAUTH Extension <http://tools.ietf.org/html/rfc4467>.
Changed data forms usage to semantic XML format (except for in-band registration).
(psa)Generalized to cover authorization tokens; added use cases for pubsub node subscriptions and XMPP account registration.
(psa)Initial published version.
(psa)First draft.
(psa)END