0.3

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1773 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0235.xml

@@ -6,8 +6,8 @@
 <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
 <xep>
 <header>
-  <title>Direct Invitations</title>
+  <title>Authorization Tokens</title>
-  <abstract>This specification defines an XMPP extension for generating, requesting, and providing invitations, which can be used in the context of Multi-User Chat rooms and other services.</abstract>
+  <abstract>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.</abstract>
   &LEGALNOTICE;
   <number>0235</number>
   <status>Experimental</status>
@@ -21,6 +21,18 @@
   <supersededby/>
   <shortname>NOT YET ASSIGNED</shortname>
   &stpeter;
+  <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>
@@ -35,69 +47,214 @@
   </revision>
 </header>
 <section1 topic='Introduction' anchor='intro'>
-  <p>&xep0045; 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 &xep0016; 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. Therefore, this specification defines an XMPP extension that enables a user to directly send an invitation to a contact, thus routing around the blocking of mediated invitations. While the main use case for this protocol is multi-user chat, nothing in the protocol prevents it from being used to invite contacts to other types of services, such as &xep0060; services or future collaboration services.</p>
+  <p>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 &xep0045; room or to subscribe to a &xep0060; node. This document defines a general method for obtaining, sharing, and using authorization tokens over XMPP.</p>
 </section1>
-<section1 topic='Obtaining an Invitation' anchor='obtain'>
+<section1 topic='Obtaining an Authorization Token' anchor='obtain'>
-  <p>In order to obtain an invitation that can be directly sent to a contact, a user requests an invitation token from the relevant service. For example, let us imagine that the user &lt;crone1@shakespeare.lit&gt; wishes to invite the contact &lt;hecate@shakespeare.lit&gt; to the chatroom &lt;darkcave@macbeth.shakespeare.lit&gt;. The user would send the following request to the room &NSNOTE;.</p>
+  <p>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 &lt;crone1@shakespeare.lit&gt; wishes to invite the consumer &lt;hecate@shakespeare.lit&gt; to the chatroom &lt;darkcave@macbeth.shakespeare.lit&gt;. Assuming that the user has already determined that the chatroom supports authorization tokens, the user would send the following request to the room &NSNOTE;.</p>
   <example caption='Token request'><![CDATA[
 <iq from='crone1@shakespeare.lit/desktop'
     id='request1'
     to='darkcave@macbeth.shakespeare.lit'
     type='get'>
-  <invitation 
+  <token xmlns='urn:xmpp:tmp:auth-token'
-      for='hecate@shakespeare.lit'
+         consumer='xmpp:hecate@shakespeare.lit'/>
-      xmlns='urn:xmpp:tmp:invite'/>
 </iq>
   ]]></example>
-  <p>If the room supports the direct invitation protocol and the user is allowed to invite contacts to the room, the room returns an invitation token to the user.</p>
+  <p>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.</p>
   <example caption='Token response'><![CDATA[
 <iq from='darkcave@macbeth.shakespeare.lit'
     id='request1'
     to='crone1@shakespeare.lit/desktop'
     type='result'>
-  <invitation 
+  <token xmlns='urn:xmpp:tmp:auth-token'
-      expires='2007-02-21T23:59:59Z'
+         consumer='xmpp:hecate@shakespeare.lit'
-      for='hecate@shakespeare.lit'
+         expires='2007-02-21T23:59:59Z'
-      jid='darkcave@macbeth.shakespeare.lit'
+         service='darkcave@macbeth.shakespeare.lit'>
-      xmlns='urn:xmpp:tmp:invite'>
     37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
-  </invitation>
+  </token>
 </iq>
   ]]></example>
-  <p>The syntax of the invitation is as follows.</p>
+  <p>The syntax of the &lt;token/&gt; element is as follows.</p>
   <ul>
-    <li>The 'expires' attribute defines a date and time when the invitation expires. Inclusion of this attribute is OPTIONAL. If included, it MUST be a DateTime as specified in &xep0082;.</li>
+    <li>The OPTIONAL 'expires' attribute defines a date and time when the token expires. If included, it MUST be a DateTime as specified in &xep0082;.</li>
-    <li>The 'for' attribute defines the JabberID of the invitee. Inclusion of this attribute is REQUIRED.</li>
+    <li>The REQUIRED 'consumer' attribute defines the URI of the entity to be authorized (e.g., an XMPP URI, mailto URI, or HTTP URL).</li>
-    <li>The 'jid' attribute defines the JabberID of the service to which the invitee is being invited. Inclusion of this attribute is REQUIRED.</li>
+    <li>The REQUIRED 'service' attribute defines the JabberID of the service for which the consumer is being authorized.</li>
-    <li>The XML character data of the &lt;invitation/&gt; element is the invitation token itself. The token MAY be generated according to any method deemed appropriate by the service implementation. It is RECOMMENED that the token be the hexadecimal representation of a Keyed-Hash Message Authentication Code (see &nistfips198a;) generated using the SHA256 hashing algorithm (see &nistfips180-2;), as described elsewhere in this document.</li>
+    <li>The OPTIONAL 'node' attribute defines a publish-subscribe node at the service; if the 'node' attribute is included, the authorization MUST be accepted only for interactions with that particular node.</li>
+    <li>The XML character data of the &lt;token/&gt; element is the authorization token itself.</li>
   </ul>
 </section1>
-<section1 topic='Sharing an Invitation' anchor='share'>
+<section1 topic='Generating an Authorization Token' anchor='generate'>
-  <p>The user can then send the invitation to the contact in an XMPP message stanza:</p>
+  <p>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;.</p>
-  <example caption='Sharing the invitation'><![CDATA[
+</section1>
+<section1 topic='Sharing an Authorization Token' anchor='share'>
+  <p>The user can then send the authorization token to the consumer in an XMPP message stanza:</p>
+  <example caption='Sharing the authorization token'><![CDATA[
 <message from='crone1@shakespeare.lit/desktop' to='hecate@shakespeare.lit'>
-  <invitation 
+  <token xmlns='urn:xmpp:tmp:auth-token'
-      expires='2007-02-21T23:59:59Z'
+         consumer='xmpp:hecate@shakespeare.lit'
-      for='hecate@shakespeare.lit'
+         expires='2007-02-21T23:59:59Z'
-      jid='darkcave@macbeth.shakespeare.lit'
+         service='darkcave@macbeth.shakespeare.lit'>
-      xmlns='urn:xmpp:tmp:invite'>
     37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
-  </invitation>
+  </token>
 </message>
   ]]></example>
 </section1>
-<section1 topic='Using an Invitation' anchor='use'>
+<section1 topic='Using an Authorization Token' anchor='use'>
-  <p>The contact then MUST then determine the identity of the service (via &xep0030;) so that it can determine how to use the invitation.</p>
+  <p>If the consumer wishes to use the token, it MUST first determine the identity of the service (via &xep0030;) so that it can decide how to proceed.</p>
-  <p>In this example, the service is a multi-user chat service. Therefore if the contact wishes to join the designated chatroom, it will include the invitation in its join request.</p>
+  <p>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 <link url='#support'>Determining Support</link> section of this document).</p>  
-  <example caption='Chatroom join with invitation'><![CDATA[
+  <section2 topic='Multi-User Chat' anchor='use-muc'>
-<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'
+    <p>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.</p>
-  <invitation xmlns='urn:xmpp:tmp:invite'>
+    <example caption='Chatroom join without token'><![CDATA[
+<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'/>
+    ]]></example>
+    <example caption='Error from chatroom'><![CDATA[
+<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>
+    ]]></example>
+    <p>The consumer would then include the authorization token in its join request.</p>
+  <example caption='Chatroom join with token'><![CDATA[
+<presence from='hecate@shakespeare.lit/broom' to='darkcave@macbeth.shakespeare.lit/Hecate'>
+  <token xmlns='urn:xmpp:tmp:auth-token'>
     37c69b1cf07a3f67c04a5ef5902fa5114f2c76fe4a2686482ba5b89323075643
-  </invitation>
+  </token>
+</presence>
+    ]]></example>
+    <p>If the token is acceptable, the service will then allow the consumer to enter the room.</p>
+    <p>Note: Although <cite>XEP-0045</cite> 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 &xep0016; 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.</p>
+  </section2>
+  <section2 topic='Publish-Subscribe' anchor='use-pubsub'>
+    <p>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.</p>
+    <example caption='Subscription request without token'><![CDATA[
+<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>
+    ]]></example>
-  <p>If the invitation is acceptable, the service will then allow the contact to enter the room.</p>
+    <example caption='Error from node'><![CDATA[
-  <p><em>Note: Detailed error flows will be added to a future version of this specification.</em></p>
+<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>
+    ]]></example>
+    <p>The contact would then include the authorization token in its subscription request.</p>
+  <example caption='Subscription request with token'><![CDATA[
+<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>
+    ]]></example>
+    <p>If the token is acceptable, the service will then allow the consumer to subscribe to the node.</p>
+  </section2>
+  <section2 topic='Account Registration' anchor='use-register'>
+    <p>In this example, the service allows new account registration using &xep0077;. The registering entity SHOULD request the registration form before attempting to register.</p>
+    <example caption='Consumer requests registration form'><![CDATA[
+<iq type='get'
+    to='contests.shakespeare.lit'
+    id='reg1'>
+  <query xmlns='jabber:iq:register'/>
+</iq>
+    ]]></example>
+    <example caption='Host returns registration form'><![CDATA[
+<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>
+    ]]></example>
+    <p>The user then SHOULD return the form:</p>
+    <example caption='User Submits Registration Form'><![CDATA[
+<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>
+    ]]></example>
+    <p>If the token is acceptable, the service will then allow the consumer to register.</p>
+  </section2>
+</section1>
+<section1 topic='Determining Support' anchor='support'>
+  <p>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 &xep0115; notations &NSNOTE;.</p>
 </section1>
 <section1 topic='Security Considerations' anchor='security'>
   <p>To follow.</p>
@@ -107,7 +264,21 @@
 </section1>
 <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
   <section2 topic='Protocol Namespaces' anchor='ns'>
-    <p>Until this specification advances to a status of Draft, its associated namespace shall be "urn:xmpp:tmp:invite"; upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
+    <p>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 &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
+  </section2>
+  <section2 topic='Field Standardization' anchor='registrar-formtypes'>
+    <p>This specification adds one field to the existing FORM_TYPE for In-Band Registration.</p>
+    <section3 topic='jabber:iq:register' anchor='registrar-formtypes-register'>
+      <code><![CDATA[
+<form_type>
+  <name>jabber:iq:register</name>
+  <field
+      var='auth-token'
+      type='text-single'
+      label='Authorization token'/>
+</form_type>
+      ]]></code>
+    </section3>
   </section2>
 </section1>
 <section1 topic='XML Schema' anchor='schema'>
@@ -116,27 +287,39 @@
 
 <xs:schema
     xmlns:xs='http://www.w3.org/2001/XMLSchema'
-    targetNamespace='urn:xmpp:tmp:invite'
+    targetNamespace='urn:xmpp:tmp:auth-token'
-    xmlns='urn:xmpp:tmp:invite'
+    xmlns='urn:xmpp:tmp:auth-token'
     elementFormDefault='qualified'>
 
-  <xs:element name='invitation'>
+  <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='for' type='xs:string' use='optional'/>
-          <xs:attribute name='jid' 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>
   ]]></code>
 </section1>
 <section1 topic='Acknowledgements' anchor='ack'>
-  <p>Thanks to Dave Cridland for his suggestions. Aspects of this specification were inspired by &rfc4467;.</p>
+  <p>Thanks to Dave Cridland and Pedro Melo for their suggestions. Aspects of this specification were inspired by &rfc4467;. Some of the terminology in this specification was borrowed from OAuth.</p>
 </section1>
 </xep>