<p>Some XMPP features must be offered by the server itself, or can't be available, that's the case of &xep0163; which is used in several places (e.g. bookmarks storage). But it can be desirable to use an external entity to manage some of these features, because it implements things that the server don't, or because it uses a special implementation useful in a particular case. Some people may also want to decentralize a feature on an entity under their control. This XEP try to solve these cases.<br/>Additionaly, a method to do generic treatments (independent of server) on stanza is also provided.</p>
<p>This XEP is complementary to priviliged entity XEP (and works in a similar way), although they can be used together or separately.</p>
<p>Here are some use cases of namespace delegation:</p>
<ul>
<li>use an external component for a PEP service because the server doesn't implement it or lacks some features</li>
<li>decentralize a server feature to an entity under client control</li>
<li>make a component which react on new user registration, independent of server implementation</li>
<li>server agnostic roster filtering</li>
</ul>
</section1>
<section1topic='Requirements'anchor='reqs'>
<p>Namespace delegation can be used in two modes:</p>
<ul>
<li><strong>admin</strong> mode, where delegation is specified by the server administrator.</li>
<li><strong>client</strong> mode, where it can be requested by any user.</li>
</ul>
<p>In <em>admin</em> mode, the managing entity manages stanza of the delegated namespace for all users registered on the server. The namespace delegation MUST be totally transparent for the managed entities.</p>
<p>In <em>client</em> mode, a managing entity MUST have an explicit authorization for any namespace he wants to use. Client SHOULD be able to check and revoke granted permissions, and if it's not possible, permissions MUST be revoked after a disconnection.</p>
</section1>
<section1topic='Glossary'anchor='glossary'>
<ul>
<li><strong>Delegated namespace</strong> — the namespace being managed by an external entity.</li>
<li><strong>Managing entity</strong> — the entity which actualy manages the delegated namespace.</li>
<li><strong>Managed entity</strong> — an entity which wants to have a namespace of its server delegated to a managing entity.</li>
</ul>
</section1>
<section1topic='Admin Mode Use Cases'anchor='admin_usecases'>
<section2topic='Delegation Request Use Case'anchor='admin_perm'>
<p>Once the managing entity is authenticated and stream is started, the entity can request to manage a namespace. It does it by sending an &IQ; stanza with <strong>'urn:xmpp:delegation:0'</strong> namespace. The &QUERY; element MUST have a type of value "request" and MAY have a 'delegation' attribute with the value "admin".</p>
<p>Namespace delegations are asked with a <delegate/> element, which MUST contain a 'namespace' attribute set to the requested namespace.</p>
<p>Only <iq/> stanza namespaces can be delegated.</p>
<examplecaption='entity asks for delegation in admin mode'><![CDATA[
<p>If the server accepts the delegation (e.g.: namespace mapping specified in configuration), it MUST return an &IQ; result stanza, with allowed delegations in <delegate> elements:</p>
<p>Note: the granted delegations MAY be different from the requested ones, according to server's configuration.</p>
<p>The server MUST then forward all requests made to itself on this namespace to the managing entity, except the requests made by the managing entity itself (see below).<br/>
The server MUST NOT forward any request made to an other entity than itself or to a bare JID within its domain.</p>
<p>When a server receives a stanza for a delegated namespace which is either directed to him (no 'to' attribute, or 'to' attribute with its own JID), or directed to the bare JID of the sender (e.g. if 'from' attribute is "<em>juliet@capulet.lit/balcony</em>" and 'to' attribute is "<em>juliet@capulet.lit</em>"), it MUST forward it to the managing entity by replacing the 'to' attribute with the JID of the managing entity:</p>
<examplecaption='Juliet sends her mood to her server via PEP'><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
id='pep1'
type='set'>
<pubsubxmlns='http://jabber.org/protocol/pubsub'>
<publishnode='http://jabber.org/protocol/mood'>
<item>
<moodxmlns='http://jabber.org/protocol/mood'>
<annoyed/>
<text>curse my nurse!</text>
</mood>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>The server gets this stanza, sees that this namespace is delegated to <em>pubsub.capulet.lit</em>, so it forwards it:</p>
<examplecaption='server delegate the stanza to pubsub.capulet.lit'><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
to='pubsub.capulet.lit'
id='delegate1'
type='set'>
<pubsubxmlns='http://jabber.org/protocol/pubsub'>
<publishnode='http://jabber.org/protocol/mood'>
<item>
<moodxmlns='http://jabber.org/protocol/mood'>
<annoyed/>
<text>curse my nurse!</text>
</mood>
</item>
</publish>
</pubsub>
</iq>
]]></example>
<p>The managing entity replies normally to the stanza:</p>
<examplecaption='pubsub.capulet.lit replies to Juliet'><![CDATA[
<p>The workflow is fully transparent for Juliet.</p>
<section3topic='Stanzas from managing entity'anchor='managing_entity_stanzas'>
<p>If a stanza is sent by the managing entity on a managed namespace, the server MUST NOT forward it. This way, the managing entity can use privileged entity to do special treatments.</p>
<p>In the following examples, <em>juliet@capulet.lit</em> has its "<em>jabber:iq:roster</em>" namespace delegated to <em>filter.capulet.lit</em>. <em>filter.capulet.lit</em> is a server agnostic component which filters allowed entities (which can be added to a roster), and sort them in enforced groups.</p>
<examplecaption='Juliet adds Romeo to her roster'><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
id='roster1'
type='set'>
<queryxmlns='jabber:iq:roster'>
<itemjid='romeo@montaigu.lit'
name='My Romeo'>
</item>
</query>
</iq>
]]></example>
<examplecaption='server forwards stanza to managing entity'><![CDATA[
<iqfrom='juliet@capulet.lit/balcony'
to='filter.capulet.lit'
id='delegate1'
type='set'>
<queryxmlns='jabber:iq:roster'>
<itemjid='romeo@montaigu.lit'
name='My Romeo'>
</item>
</query>
</iq>
]]></example>
<p><em>filter.capulet.lit</em> accepts to add Romeo, but all JIDs with a <em>montaigu.lit</em> must be in a "Rivals" group, so it first returns a success result (Romeo is accepted).</p>
<examplecaption='server forward the result with the initial id'><![CDATA[
<iqto='juliet@capulet.lit/balcony'
id='roster1'
type='result' />
]]></example>
<p>At this stade, the entity is accepted, but not added to the roster. <em>filter.capulet.lit</em> is also a privileged entity which can manage "<em>jabber:iq:roster</em>", so it uses this ability to add Romeo in the enforced group:</p>
<examplecaption='filter.capulet.lit uses privileged entity to add Romeo'><![CDATA[
<iqto='juliet@capulet.lit'
from='filter.capulet.lit'
id='roster2'
type='set'>
<queryxmlns='jabber:iq:roster'>
<itemjid='romeo@montaigu.lit'
name='My Romeo'>
<group>Rivals</group>
</item>
</query>
</iq>
]]></example>
<p>The namespace is delegated, but as the stanza is from the managing entity, the server manages it normally. The entity is also privileged, so it can change the stanza of Juliet, the server accepts:</p>
<examplecaption='server accept new entity in roster'><![CDATA[
<iqto='filter.capulet.lit'
from='juliet@capulet.lit'
id='roster2'
type='result'/>
]]></example>
<p>The server will then send the roster pushes (with the enforced group) normally.</p>
</section3>
</section2>
</section1>
<section1topic='Client Mode Use Cases'anchor='client_usecases'>
<section2topic='Client Delegation Request Use Case'anchor='client_delegation'>
<p>In <em>client</em> mode, the managing entity is not certified by the server administrator, so the delegation MUST be <strong>explicitly</strong> allowed by the managed entity. This is initiated by the managing entity (it can be after an interaction with a managed entity, like a subscription). It's done in the same way as for <em>admin</em> mode with the following exceptions:</p>
<ol>
<li>the delegation type is <em>client</em> instead of <em>admin</em></li>
<li>the delegation is done per entity, so the managed entity MUST be specified in a 'to' attribute</li>
</ol>
<p>If an entity want to manage PEP service for Juliet, it can ask the delegation like this:
</p>
<examplecaption='managing entity asks for namespace delegation for one particular entity'><