XEP-0235: Authorization Tokens

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.

Document Information

Author Information

Peter Saint-Andre

JabberID: stpeter@jabber.org
URI: https://stpeter.im/

Legal Notices

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).

Discussion Venue

Relation to XMPP

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.

Conformance Terms

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
       9.2.2. urn:xmpp:tmp:auth-token
10. XML Schema
11. Acknowledgements
Notes
Revision History

1. Introduction

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.

2. Obtaining an Authorization Token

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>

3. Generating an Authorization Token

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:

<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>

5. Using an Authorization Token

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).

5.1 Multi-User Chat

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'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
          <value>urn:xmpp:tmp:auth-token</value>
        </field>
        <field var='auth-token'
               type='text-single'
               label='Provide Your Authorization Token'/>
      </x>
    </token-required>
  </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'>
  <x xmlns='jabber:x:data' type='submit'>
    <field var='FORM_TYPE' type='hidden'>
      <value>urn:xmpp:tmp:auth-token</value>
    </field>
    <field var='auth-token'>
      <value>
        37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
      </value>
    </field>
  </x>
</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.

5.2 Publish-Subscribe

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>

Example 8. Error from node

<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'>
      <x xmlns='jabber:x:data' type='form'>
        <field var='FORM_TYPE' type='hidden'>
          <value>urn:xmpp:tmp:auth-token</value>
        </field>
        <field var='auth-token'
               type='text-single'
               label='Provide Your Authorization Token'/>
      </x>
    </token-required>
  </error>
</iq>

The contact would then include the authorization token in its join 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'/>
    <x xmlns='jabber:x:data' type='submit'>
      <field var='FORM_TYPE' type='hidden'>
        <value>urn:xmpp:tmp:auth-token</value>
      </field>
      <field var='auth-token'>
        <value>
          37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
        </value>
      </field>
    </x>
  </pubsub>
</iq>

If the token is acceptable, the service will then allow the consumer to subscribe to the node.

5.3 Account Registration

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.

6. Determining Support

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).

7. Security Considerations

8. IANA Considerations

9. XMPP Registrar Considerations

9.1 Protocol Namespaces

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].

9.2 Field Standardization

This specification adds one field to the existing FORM_TYPE for In-Band Registration and registers a new FORM_TYPE of "urn:xmpp:tmp:auth-token".

9.2.1 jabber:iq:register

<form_type>
  <name>jabber:iq:register</name>
  <field
      var='auth-token'
      type='text-single'
      label='Authorization token'/>
</form_type>

9.2.2 urn:xmpp:tmp:auth-token

<form_type>
  <name>urn:xmpp:tmp:auth-token</name>
  <doc>XEP-0235</doc>
  <desc>Standardization of fields related to authorization tokens.</desc>
  <field
      var='auth-token'
      type='text-single'
      label='Authorization token'/>
</form_type>

10. XML Schema

<?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>

11. Acknowledgements

Thanks to Dave Cridland for his suggestions. Aspects of this specification were inspired by RFC 4467 [12]. Some of the terminology in this specification was borrowed from OAuth.

Notes

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>.