Auth Component

From OnSIP Developer Wiki

Contents 1 Overview 1.1 JID 1.2 Command Nodes 2 authorize-plain 2.1 Authorization Requirements 2.2 Input Fields 2.3 Single Stage Execution 2.3.1 Request to commands.auth.xmpp.onsip.com 2.4 Multi-stage Execution 2.5 Response Handling 2.5.1 Success 2.5.1.1 Response Fields 2.5.1.2 Successful Response 2.5.2 Errors 2.5.2.1 Error Response 2.6 Additional Information

Overview

The Junction Networks XMPP API performs commands and publishes information based around SIP addresses. In order to allow any JID to perform a command for a SIP address or subscribe to PubSub data regarding a SIP address or SIP domain the JID must authorize itself (or another JID) by providing a SIP user address and a password to the Auth component.

JID

commands.auth.xmpp.onsip.com

Command Nodes

• authorize-plain

authorize-plain

Authorize a JID for a SIP address using a plain text password.

Authorization Requirements

none

Input Fields

sip-address 

The SIP user address to authorize

password 

The web portal password of the user that owns the SIP user address

jid 

(optional) bare JID of the JID to authorize, if not provided the JID in the IQ from attribute will be assumed

auth-for-all 

(optional) boolean indicating whether or not to authorize for all SIP user addresses owned by the owner of sip-address. Additional SIP addresses that this request authorizes subscription to will be listed in the response. Default is false

Single Stage Execution

To add the authorization capability to your application you may execute this call command node in a single step. Submit an ad-hoc request with input fields named above to the Auth component. The jid parameter is optional, if submitted the parameter can be used to authorize a third party JID for the SIP address. In the normal case of authorizing the requesting JID however, the parameter may be excluded.

Request to commands.auth.xmpp.onsip.com

<iq type="set" to="commands.auth.xmpp.onsip.com" id="ab31a" >
  <command xmlns="http://jabber.org/protocol/commands" node="authorize-plain">
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="sip-address" >
        <value>foo@example.onsip.com</value>
      </field>
      <field type="text-private" var="password" >
        <value>goodpassword</value>
      </field>
      <field type="hidden" var="jid" />
    </x>
  </command>
</iq>

Multi-stage Execution

N/A

Response Handling

Upon completion of an Ad-Hoc command, an IQ stanza will be returned containing a command element with a status of 'completed'. However by XEP 0050 standards, this does not necessarily indicate success (or failure). Success or failure of command execution will be indicated by the type attribute of the IQ stanza. A value of result indicates success, and type error indicates failure. Please see RFC 3920: Section 9.3 Stanza Errors for more information.

Success

Upon a successful execution of the authorize-plain command a single field is returned. The field contains the expiration datetime of the authorization in W3C coordinated universal time (UTC). In order to continue service without interruptions to due authorization failures, clients MUST re-authorize for each SIP address before the expiration time passes

Response Fields

expires 

a W3C formatted UTC datetime indicating the expiration of the subscription

Successful Response

<iq from="commands.auth.xmpp.onsip.com" type="result" 
    to="foo@example.onsip.com/resource" id="aaeea" >
  <command xmlns="http://jabber.org/protocol/commands" status="completed" 
           node="authorize-plain" 
           sessionid="8588124ce9e909f789544567197a04ec" >
    <note type="info" >
      JID 'foo@example.onsip.com' has been authorized to access resources for 
      SIP Address(es) 'foo@example.onsip.com' until 2010-04-27T20:51:57Z
    </note>
    <x xmlns="jabber:x:data" type="result" >
      <field type="fixed" var="expires" >
        <value>2010-04-27T20:51:57Z</value>
      </field>
      <field type="fixed" var="sip" >
        <value>foo@example.onsip.com</value>
      </field>
    </x>
  </command>
</iq>

Errors

Errors during command execution will be communicated back using standard Ad-Hoc command errors, which in turn leverage standard XMPP stanza errors.

Warning: The text child of the error element attempts to provide a general description of the errors that may have occurred. Therefore the content of the the text node should NOT be relied upon to provide a key-value pairing of input parameters to errors.

Error Response

<iq from="commands.auth.xmpp.onsip.com" type="error" xml:lang="en" 
    to="foo@example.onsip.com/resource" id="ab33a" >
  <command xmlns="http://jabber.org/protocol/commands" node="authorize-plain" 
         sessionid="1ae88e4af0798f05e34246923ab5aeaf" >
    <x xmlns="jabber:x:data" type="submit" >
      <field type="text-single" var="sip-address" >
        <value>foo@example.onsip.com</value>
      </field>
      <field type="text-private" var="password" >
        <value>badpassword</value>
      </field>
      <field type="hidden" var="jid" />
    </x>
  </command>
  <error type="modify" code="400" >
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      Execution Errors; base Authorization failed - invalid username or password.; missing response
    </text>
    <bad-action xmlns="http://jabber.org/protocol/commands"/>
  </error>
</iq>

Additional Information

N/A