XEP-0235: OAuth Over XMPP

This specification defines an XMPP extension for delegating access to protected resources over XMPP, using the OAuth protocol. 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. This specification assumes that OAuth tokens will be acquired via HTTP as defined in the core OAuth specification, then presented over XMPP to a Service Provider. The Protected Resources accessible over XMPP might include groupchat rooms, data feeds hosted at publish-subscribe nodes, media relays, communication gateways, and other items of interest.


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

Series: XEP
Number: 0235
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Standards Track
Version: 0.4
Last Updated: 2008-08-07
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/OAuth Over XMPP (XEP-0235)>


Author Information

Peter Saint-Andre

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


Legal Notices

Copyright

This XMPP Extension Protocol is copyright (c) 1999 - 2008 by the XMPP Standards Foundation (XSF).

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

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

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


Table of Contents


1. Introduction
2. Protocol Flow
3. Determining Support
4. Security Considerations
    4.1. Signature Generation Algorithm
    4.2. Replay Attacks
5. IANA Considerations
6. XMPP Registrar Considerations
    6.1. Protocol Namespaces
7. XML Schema
8. Acknowledgements
Notes
Revision History


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.

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.

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 via XMPP, 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 would be represented in XMPP as follows.

Example 1. Pubsub subscription request with token

<iq type='set'
    from='travelbot@findmenow.tld/bot'
    to='feeds.worldgps.tld'
    id='sub1'>
  <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_token>ad180jjd733klru7</oauth_token>
      <oauth_signature_method>HMAC-SHA1</oauth_signature_method>
      <oauth_signature>wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D</oauth_signature>
    </oauth>
  </pubsub>
</iq>
  

3. Determining Support

If a service provides and accepts authorization tokens, it MUST advertise support for the 'urn:xmpp:tmp:oauth' namespace in its disco#info replies (if provided) its Entity Capabilities [4] notations (see Protocol Namespaces regarding issuance of one or more permanent namespaces).

4. Security Considerations

4.1 Signature Generation Algorithm

When sending OAuth Access Tokens over XMPP, the signature method MUST be HMAC-SHA1. The Signature Base String SHALL be constructed from the following items:

As an example, consider the following stanza:

<iq to="x@example.com" from="y@example.org" id="1234">
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='mynode'/>
    <oauth xmlns='urn:xmpp:tmp:oauth'>
      <oauth_consumer_key>foo</oauth_consumer_key>
      <oauth_token>bar</oauth_token>
      <oauth_signature_method>HMAC-SHA1</oauth_signature_method>
      <oauth_signature>h2vvES3WQpdYmjzUK7Fl2G1Nez8=</oauth_signature>
    </oauth>
  </pubsub>
</iq>
    

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

iq&x%40example.com%26y%40example.org&oauth_consumer_key%3Dfoo\
%40oauth_signature_method%3DHMAC-SHA1%40oauth_token%3Dbar
    

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

    h2vvES3WQpdYmjzUK7Fl2G1Nez8=
    

4.2 Replay Attacks

Signatures generated according to the signature generation algorithm might be subject to replay attacks. However, inclusions of the XMPP "to" and "from" addresses limits these attackes to compromised servers or client-to-server connections. OAuth tokens SHOULD be sent only over TLS-encrypted client-to-server connections, and all server-to-server connections SHOULD be TLS-enabled. Additional security can be provided using appropriate methods for the end-to-end encryption of XMPP traffic, such as Current Jabber OpenPGP Usage [5], RFC 3923 [6] Encrypted Session Negotiation [7], or End-to-End XML Streams [8].

5. IANA Considerations

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

6. XMPP Registrar Considerations

6.1 Protocol Namespaces

Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:oauth"; 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]. The permanent namespace "urn:xmpp:oauth" will be requested, which is thought to be unique per the XMPP Registrar's requirements.

7. 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_token_secret' type='xs:string'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

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

</xs:schema>
  

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


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. OAuth Core 1.0 <http://oauth.net/core/1.0/>.

4. XEP-0115: Entity Capabilities <http://www.xmpp.org/extensions/xep-0115.html>.

5. XEP-0027: Current Jabber OpenPGP Usage <http://www.xmpp.org/extensions/xep-0027.html>.

6. RFC 3923: End-to-End Signing and Object Encryption for the Extensible Messaging and Presence Protocol (XMPP) <http://tools.ietf.org/html/rfc3923>.

7. XEP-0116: Encrypted Session Negotiation <http://www.xmpp.org/extensions/xep-0116.html>.

8. XEP-0246: End-to-End XML Streams <http://www.xmpp.org/extensions/xep-0246.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>.


Revision History

Version 0.4 (2008-08-07)

Incorporated consensus reached at XMPP Summit #5: specified that HTTP is used except for presentation of an Access Token, corrected signature generation algorithm, specified security considerations, and removed invitation and account registration use cases.

(psa)

Version 0.3 (2008-03-31)

Changed data forms usage to semantic XML format (except for in-band registration).

(psa)

Version 0.2 (2008-03-27)

Generalized to cover authorization tokens; added use cases for pubsub node subscriptions and XMPP account registration.

(psa)

Version 0.1 (2008-03-05)

Initial published version.

(psa)

Version 0.0.1 (2008-02-20)

First draft.

(psa)

END