XEP-0235: OAuth Over XMPP

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.

Table of Contents

1. Introduction

Although authentication is required in order to access the XMPP network, in some situations it is desirable to require authorization in order for an authenticated entity to access certain resources on the network. For example, authorization may be required to join a Multi-User Chat [1] room, subscribe to a Publish-Subscribe [2] node, or to access other resources of interest (such as a media relay or communications gateway).

Dedicated technologies exist for authorization. One such technology is OAuth [3], as defined at <http://oauth.net/core/1.0/>. In the language of OAuth, a User can authorize a Consumer to access a Protected Resource that is hosted by a Service Provider; this authorization is encapsulated in a token that the User requests from the Service Provider, that the User shares with the Consumer, and that the Consumer then presents to the Service Provider in an access request.

This specification assumes that OAuth Access Tokens will be acquired outside the XMPP (i.e., via HTTP as defined in the core OAuth specification) and merely presented over XMPP when sending a protocol-specific access request.

2. Protocol Flow

The typical scenario is for a Consumer to request the authorization to act as a delegated authority on behalf of the User to access a Protected Resource owned by the User at a Service Provider. For example, the owner of a pubsub node could allow a remote entity to publish to that node (the single lines "---" show protocol flows over HTTP and the double lines "===" show protocol flows over XMPP):

Consumer                  Service Provider
   |                             |
   |  request a Request Token    |
   |---------------------------->|
   |  grant the Request Token    |
   |<----------------------------|
   |                             |
   |  [Consumer redirects User   |
   |   to Service Provider]      |
   |                             |
   |  request an Access Token    |
   |---------------------------->|
   |  grant the Access Token     |
   |<----------------------------|
   |  access Protected Resource  |
   |============================>|
   |                             |
  

Before presenting an access token to a Service Provider in a protocol-specific access request, a Consumer SHOULD verify that the Service Provider supports this protocol, as described under the Determining Support section of this document.

Consider the example of a User (say, <world-traveler@example.com>) who wishes to authorize a Consumer (say, an application called FindMeNow as represented by the JID <travelbot@findemenow.tld>) to access the User's geolocation feed at a Service Provider called WorldGPS (as represented by a publish-subscribe node of <feeds.worldgps.tld/world-traveler>). The order of events might be as follows.

1. WorldGPS and FindMeNow have agreed upon a certificate and secret for FindMeNow to use when communicating with WorldGPS.
2. WorldGPS maintains a feed for the User's location data in an XMPP PubSub Node.
3. The User visits FindMeNow.tld and requests real-time updates from his WorldGPS feed.
4. FindMeNow, over HTTP, requests a "request token" from WorldGPS's pubsub service, signing it with the agreed-upon certificate and secret.
5. WorldGPS, if the signature was valid, sends FindMeNow a "request token."
6. FindMeNow then redirects the user to a WorldGPS webpage.
7. On the WorldGPS webpage, the User logs in (or is already logged in) and is then asked whether to approve of FindMeNow having read-only access to his geolocation information.
8. The User approves the request and WorldGPS redirects the User back to FindMeNow.
9. FindMeNow, over HTTP, requests an "access token" (again signing it) and now using the "request token" approved by the User.
10. WorldGPS, if the signature is correct and the request token was approved, replies with an access token.
11. FindMeNow, over XMPP, subscribes to the User's pubsub node using the access token.

As a result, FindMeNow gets updated every time the User publishes items to his geolocation node at WorldGPS.

Steps 1 through 10 occur via HTTP. Step 11 occurs via XMPP.

3. Access Request Format

The access request MUST include the following parameters:

• oauth_consumer_key
• oauth_nonce
• oauth_signature
• oauth_signature_method
• oauth_timestamp
• oauth_token

The access MAY also include the "oauth_version" parameter

An example follows.

Example 1. Pubsub subscription request with OAuth access token

<iq from='travelbot@findmenow.tld/bot'
    id='sub1'
    to='feeds.worldgps.tld'
    type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='bard_geoloc'/>
    <oauth xmlns='urn:xmpp:tmp:oauth'>
      <oauth_consumer_key>0685bd9184jfhq22</oauth_consumer_key>
      <oauth_nonce>4572616e48616d6d65724c61686176</oauth_nonce>
      <oauth_signature>wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D</oauth_signature>
      <oauth_signature_method>HMAC-SHA1</oauth_signature_method>
      <oauth_timestamp>1218137833</oauth_timestamp>
      <oauth_token>ad180jjd733klru7</oauth_token>
      <oauth_version>1.0</oauth_version>
    </oauth>
  </pubsub>
</iq>
  

4. Signature Generation Algorithm

When sending an OAuth access request over XMPP, the signature method SHOULD be HMAC-SHA1. The Signature Base String SHALL be constructed from the following items:

• The HTTP request method SHALL be the qname of the XMPP stanza element used, that is, either "message" or "presence" or "iq".
• The request URL SHALL be the 'from' address of the XMPP stanza concatenated with the ampersand character "&" and the 'to' address of the XMPP stanza.
• The normalized request parameters string SHALL be all of the oauth_* parameters included in the <oauth/> element (except oauth_signature).

As an example, consider the following stanza:

<iq from='travelbot@findmenow.tld/bot'
    id='sub1'
    to='feeds.worldgps.tld'
    type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='bard_geoloc'/>
    <oauth xmlns='urn:xmpp:tmp:oauth'>
      <oauth_consumer_key>0685bd9184jfhq22</oauth_consumer_key>
      <oauth_nonce>4572616e48616d6d65724c61686176</oauth_nonce>
      <oauth_signature>wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D</oauth_signature>
      <oauth_signature_method>HMAC-SHA1</oauth_signature_method>
      <oauth_timestamp>1218137833</oauth_timestamp>
      <oauth_token>ad180jjd733klru7</oauth_token>
      <oauth_version>1.0</oauth_version>
    </oauth>
  </pubsub>
</iq>
  

The Signature Base String would be as follows (where line endings have been added for readability and are denoted by the "\" character):

iq%26travelbot%40findmenow.tld%2Fbot%26feeds.worldgps.tld%26\
oauth_consumer_key%3D0685bd9184jfhq22%26\
oauth_nonce%3D4572616e48616d6d65724c61686176%26\
oauth_signature_method%3DHMAC-SHA1%26\
oauth_timestamp%3D1218137833%26\
oauth_token%3Dad180jjd733klru7%26\
oauth_version%3D1.0
  

Assuming a consumer secret of 'consumersecret' and a token secret of 'tokensecret', the signature will be:

    Z0F5zmPWwbunk5dc2hNBn1NgBj4=
  

5. Error Handling

If a Service Provider rejects a Consumer's access request, the Service Provider SHOULD return either a <bad-request/> or <not-authorized/> stanza error, with an appropriate OAuth-specific error condition as described in the following table.

An example follows.

Example 2. OAuth-specific error

<iq from='feeds.worldgps.tld'
    id='sub1'
    to='travelbot@findmenow.tld/bot'
    type='error'>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <invalid-nonce xmlns='urn:xmpp:tmp:oauth:errors'/>
  </error>
</iq>
  

6. Determining Support

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:tmp:oauth" in response to Service Discovery [4] information requests (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

Example 3. Service discovery information request

<iq from='travelbot@findmenow.tld/bot'
    id='disco1'
    to='feeds.worldgps.tld'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  

Example 4. Service discovery information response

<iq from='feeds.worldgps.tld'
    id='disco1'
    to='travelbot@findmenow.tld/bot'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:tmp:oauth'/>
    ...
  </query>
</iq>
  

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in Entity Capabilities [5]. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

7. Security Considerations

8. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [10].

9. XMPP Registrar Considerations

10. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:tmp:oauth'
    xmlns='urn:xmpp:tmp:oauth'
    elementFormDefault='qualified'>

  <xs:element name='oauth'>
    <xs:complexType>
      <xs:choice>
        <xs:element name='oauth_consumer_key' type='xs:string'/>
        <xs:element name='oauth_nonce' type='xs:string'/>
        <xs:element name='oauth_signature' type='xs:string'/>
        <xs:element name='oauth_signature_method' type='xs:string'/>
        <xs:element name='oauth_timestamp' type='xs:string'/>
        <xs:element name='oauth_token' type='xs:string'/>
        <xs:element name='oauth_version' type='xs:string'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

</xs:schema>
    

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:tmp:oauth:errors'
    xmlns='urn:xmpp:tmp:oauth:errors'
    elementFormDefault='qualified'>

  <xs:element name='duplicated-parameter' type='empty'/>
  <xs:element name='invalid-consumer-key' type='empty'/>
  <xs:element name='invalid-nonce' type='empty'/>
  <xs:element name='invalid-signature' type='empty'/>
  <xs:element name='invalid-token' type='empty'/>
  <xs:element name='missing-parameter' type='empty'/>
  <xs:element name='token-required' type='empty'/>
  <xs:element name='unsupported-parameter' type='empty'/>
  <xs:element name='unsupported-signature-method' type='empty'/>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>
    

11. Acknowledgements

The author gratefully acknowledges the contributions of Blaine Cook, Leah Culver, Kellan Elliott-McCrea, Seth Fitzsimmons, Nathan Fritz, Evan Henshaw-Plath, Joe Hildebrand, and Ralph Meijer to the content of this specification, as provided during the XMPP Summit held in Portland, Oregon, on July 21 and 22, 2008. Thanks also to Dave Cridland and Pedro Melo for their comments on an early draft.

Appendices

Appendix A: Document Information

Series: XEP
Number: 0235
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.6
Last Updated: 2008-08-07
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: NOT_YET_ASSIGNED
Source Control: HTML  RSS

Appendix B: Author Information

Appendix C: Legal Notices

Appendix D: 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.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata may be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements 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".

Appendix G: Notes

Appendix H: Revision History

END