xeps/xep-0235.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>OAuth Over XMPP</title>
  <abstract>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 in an access request. 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.</abstract>
  &LEGALNOTICE;
  <number>0235</number>
  <status>Experimental</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  &stpeter;
  <revision>
    <version>0.7</version>
    <date>2009-03-24</date>
    <initials>psa</initials>
    <remark><p>Changed protocol namespace from urn:xmpp:tmp:oauth to urn:xmpp:oauth:0 to conform to XMPP Registrar policies; clarified protocol flow and error handling; corrected examples.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2008-08-07</date>
    <initials>psa</initials>
    <remark><p>Clarified error handling and service discovery.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2008-08-07</date>
    <initials>psa</initials>
    <remark><p>More clearly specified access request format; corrected examples to incorporate nonce, timestamp, and version; modified request URL syntax to follow XML canonicalization order; changed HMAC-SHA1 from MUST to SHOULD.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2008-08-07</date>
    <initials>psa</initials>
    <remark><p>Incorporated consensus reached at XMPP Summit #5: narrowed the scope to cover OAuth only, specified that HTTP is used except for sending the access request via XMPP, corrected signature generation algorithm, specified security considerations, and removed invitation and account registration use cases.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2008-03-31</date>
    <initials>psa</initials>
    <remark><p>Changed data forms usage to semantic XML format (except for in-band registration).</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2008-03-27</date>
    <initials>psa</initials>
    <remark><p>Generalized to cover authorization tokens; added use cases for pubsub node subscriptions and XMPP account registration.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2008-03-05</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2008-02-20</date>
    <initials>psa</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>

<section1 topic='Introduction' anchor='intro'>
  <p>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 &xep0045; room, subscribe to a &xep0060; node, or to access other resources of interest (such as a media relay or communications gateway).</p>
  <p>Dedicated technologies exist for authorization. One such technology is &oauth;, as defined at &lt;<link url='http://oauth.net/core/1.0/'>http://oauth.net/core/1.0/</link>&gt;. 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.</p>
  <p>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.</p>
</section1>

<section1 topic='Protocol Flow' anchor='flow'>
  <p>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):</p>
  <code><![CDATA[
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  |
   |============================>|
   |                             |
  ]]></code>
  <p>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 <link url='#support'>Determining Support</link> section of this document.</p>
  <p>Consider the example of a User (say, &lt;world-traveler@example.com&gt;) who wishes to authorize a Consumer (say, an application called FindMeNow as represented by the JID &lt;travelbot@findmenow.tld&gt;) to access the User's geolocation feed at a Service Provider called WorldGPS (as represented by a publish-subscribe node of &lt;feeds.worldgps.tld/world-traveler&gt;). The order of events might be as follows.</p>
  <ol start='1'>
    <li>FindMeNow has registered as a Consumer for WorldGPS' API and has been assigned an OAuth consumer key and secret for use in its dealings with WorldGPS.</li>
    <li>The User registers with WorldGPS, which creates a feed for the User's location data in an XMPP PubSub Node at WorldGPS.</li>
    <li>The User visits FindMeNow.tld and requests real-time updates from his WorldGPS feed.</li>
    <li>FindMeNow, over HTTP, requests an OAuth "request token" from WorldGPS, signing it with FindMeNow's OAuth consumer key and secret.</li>
    <li>WorldGPS, if the signature was valid, sends FindMeNow an OAuth "request token."</li>
    <li>FindMeNow then redirects the user to a WorldGPS webpage.</li>
    <li>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.</li>
    <li>The User approves the request and WorldGPS redirects the User back to FindMeNow.</li>
    <li>FindMeNow, over HTTP, requests an OAuth "access token" from WorldGPS, signing the request with the "request token" that has now been approved by the User.</li>
    <li>WorldGPS, if the signature is correct and the request token was approved, replies to FindMeNow with an OAuth "access token".</li>
    <li>FindMeNow, over XMPP, subscribes to the User's pubsub node using the OAuth "access token" as described below.</li>
  </ol>
  <p>As a result, FindMeNow gets updated every time the User publishes items to his geolocation node at WorldGPS.</p>
  <p>Steps 1-10 describe OAuth's standard HTTP flow and represent an out-band means for obtaining OAuth access tokens for use in XMPP operations.</p>
</section1>

<section1 topic='Access Request Format' anchor='request'>
  <p>The access request MUST include the following parameters:</p>
  <ul>
    <li>oauth_consumer_key</li>
    <li>oauth_nonce</li>
    <li>oauth_signature (note: in XMPP this value is <strong>not</strong> escaped)</li>
    <li>oauth_signature_method</li>
    <li>oauth_timestamp</li>
    <li>oauth_token</li>
  </ul>
  <p>The access MAY also include the "oauth_version" parameter</p>
  <p>An example follows.</p>
  <example caption='Pubsub subscription request with OAuth access token'><![CDATA[
<iq from='travelbot@findmenow.tld/bot'
    id='sub1'
    to='feeds.worldgps.tld'
    type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe jid='travelbot@findmenow.tld' node='bard_geoloc'/>
    <oauth xmlns='urn:xmpp:oauth:0'>
      <oauth_consumer_key>0685bd9184jfhq22</oauth_consumer_key>
      <oauth_nonce>4572616e48616d6d65724c61686176</oauth_nonce>
      <oauth_signature>9PQkM4YKgaM067wqrDGshXOwDW0=</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>
  ]]></example>
</section1>

<section1 topic='Signature Generation Algorithm' anchor='signature'>
  <p>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:</p>
  <ul>
    <li>The HTTP request method SHALL be the qname of the XMPP stanza element used, that is, either "message" or "presence" or "iq".</li>
    <li>The request URL SHALL be the 'from' address of the XMPP stanza concatenated with the ampersand character "&amp;" and the 'to' address of the XMPP stanza.</li>
    <li>The normalized request parameters string SHALL be all of the oauth_* parameters included in the &lt;oauth/&gt; element (except oauth_signature).</li>
  </ul>
  <p>As an example, consider the stanza shown above.</p>
  <p>The Signature Base String would be as follows (where line endings have been added for readability and are denoted by the "\" character):</p>
  <code><![CDATA[
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
  ]]></code>
  <p>Assuming a consumer secret of 'consumersecret' and a token secret of 'tokensecret', the signature will be:</p>
  <code><![CDATA[
    9PQkM4YKgaM067wqrDGshXOwDW0=
  ]]></code>
</section1>

<section1 topic='Error Handling' anchor='error'>
  <p>If a Service Provider rejects a Consumer's request to access a Protected Resource over XMPP, the Service Provider MUST return an XMPP stanza error. The XMPP error condition SHOULD be either &badrequest; or &notauthorized; and the stanza SHOULD include an OAuth-specific error condition as described in the following table.</p>
  <table caption='Application-Specific Error Conditions'>
    <tr>
      <th>OAuth-Specific Condition</th>
      <th>Generic Condition</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>&lt;duplicated-parameter/&gt;</td>
      <td>&badrequest;</td>
      <td>One of the oauth_* elements was included more than once.</td>
    </tr>
    <tr>
      <td>&lt;invalid-consumer-key/&gt;</td>
      <td>&notauthorized;</td>
      <td>The Consumer's OAuth consumer key is not valid.</td>
    </tr>
    <tr>
      <td>&lt;invalid-nonce/&gt;</td>
      <td>&notauthorized;</td>
      <td>The provided nonce is invalid; it might have already been used.</td>
    </tr>
    <tr>
      <td>&lt;invalid-signature/&gt;</td>
      <td>&notauthorized;</td>
      <td>The provided signature is invalid; the Consumer needs to confirm that the signature base string is calculated correctly.</td>
    </tr>
    <tr>
      <td>&lt;invalid-token/&gt;</td>
      <td>&notauthorized;</td>
      <td>The provided access token is invalid; it might have been revoked.</td>
    </tr>
    <tr>
      <td>&lt;missing-parameter/&gt;</td>
      <td>&badrequest;</td>
      <td>One of the required oauth_* elements is missing.</td>
    </tr>
    <tr>
      <td>&lt;token-required/&gt;</td>
      <td>&notauthorized;</td>
      <td>The Consumer did not include an OAuth access token in its request; this error condition is XMPP-specific and does not have a counterpart in the OAuth specification.</td>
    </tr>
    <tr>
      <td>&lt;unsupported-parameter/&gt;</td>
      <td>&badrequest;</td>
      <td>The &lt;oauth/&gt; stanza contains unknown or unsupported parameters.</td>
    </tr>
    <tr>
      <td>&lt;unsupported-signature-method/&gt;</td>
      <td>&badrequest;</td>
      <td>The specified signature method is not supported by the server.</td>
    </tr>
  </table>
  <p>An example follows.</p>
  <example caption='OAuth-specific error'><![CDATA[
<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:oauth:0:errors'/>
  </error>
</iq>
  ]]></example>
</section1>

<section1 topic='Determining Support' anchor='support'>
  <p>If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:oauth:0" in response to &xep0030; information requests &NSNOTE;.</p>
  <example caption="Service discovery information request"><![CDATA[
<iq from='travelbot@findmenow.tld/bot'
    id='disco1'
    to='feeds.worldgps.tld'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  ]]></example>
  <example caption="Service discovery information response"><![CDATA[
<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:oauth:0'/>
  </query>
</iq>
  ]]></example>
  <p>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 &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
</section1>


<section1 topic='Security Considerations' anchor='security'>
  <section2 topic='Replay Attacks' anchor='security-replay'>
    <p>Signatures generated according to the signature generation algorithm might be subject to replay attacks. However, inclusion of the XMPP "from" and "to" addresses limits these attacks to compromised servers or client-to-server connections. In addition, inclusion of the nonce value also helps to prevent replay attacks.</p>
  </section2>
  <section2 topic='Encryption' anchor='security-encryption'>
    <p>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 &xep0027;, &rfc3923; &xep0116;, or &xep0246;.</p>
  </section2>
</section1>

<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>

<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>This specification defines the following XML namespace:</p>
    <ul>
      <li>urn:xmpp:oauth:0</li>
    </ul>
    <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  </section2>
  <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
  </section2>
</section1>

<section1 topic='XML Schema' anchor='schema'>
  <section2 topic='Protocol Namespace' anchor='schema-proto'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:oauth:0'
    xmlns='urn:xmpp:oauth:0'
    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>
    ]]></code>
  </section2>
  <section2 topic='Error Namespace' anchor='schema-error'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='urn:xmpp:oauth:0:errors'
    xmlns='urn:xmpp:oauth:0: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>
    ]]></code>
  </section2>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>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. Seth Fitzsimmons checked many details and provided text regarding the protocol flow and error handling.</p>
</section1>

</xep>