[Sommaire] [Imprimer]

   1  #LyX 1.1 created this file. For more info see http://www.lyx.org/
   2  \lyxformat 218
   3  \textclass docbook
   4  \language english
   5  \inputencoding auto
   6  \fontscheme default
   7  \graphics default
   8  \paperfontsize default
   9  \spacing single 
  10  \papersize Default
  11  \paperpackage a4
  12  \use_geometry 0
  13  \use_amsmath 0
  14  \paperorientation portrait
  15  \secnumdepth 3
  16  \tocdepth 3
  17  \paragraph_separation indent
  18  \defskip medskip
  19  \quotes_language english
  20  \quotes_times 2
  21  \papercolumns 1
  22  \papersides 1
  23  \paperpagestyle default
  24  
  25  \layout Title
  26  
  27  eGroupWare XML-RPC/SOAP Methodology
  28  \layout Author
  29  
  30  (C) 2001-2004 Miles Lott
  31  \layout Author
  32  
  33  milos@groupwhere.org
  34  \layout Date
  35  
  36  August 23, 2001 and December 29, 2003
  37  \layout Standard
  38  
  39  additions made September 3, 2001.
  40  \layout Standard
  41  
  42  This document is very preliminary, but describes a working system.
  43  \layout Section
  44  
  45  System level requests
  46  \layout Subsection
  47  
  48  Login and authentication
  49  \layout Standard
  50  
  51  Authentication for user logins is handled internally no differently than
  52   for the typical eGroupWare login via web browser.
  53   Server logins, added for XML-RPC and SOAP, are only slightly different.
  54   For either protocol, user and server login and authentication and subsequent
  55   requests are handled by their respective server apps, xmlrpc.php and soap.php.
  56   A server is identified by a custom HTTP header, without which a normal
  57   user login will be undertaken.
  58  \layout Standard
  59  
  60  A client or server sends the appropriate XML-RPC or SOAP packet containing
  61   host, user, and password information to the phpgw server.
  62   The server then assigns a sessionid and key, which is returned to the client
  63   in the appropriate format.
  64  \layout Standard
  65  
  66  Our current method for authenticating requests after successful login is
  67   via the Authorization: Basic HTTP header to be sent by the client or requesting
  68   server.
  69   The format of this header is a base64 encoding of the assigned sessionid
  70   and kp3 variables, seperated by a ':'.
  71  \layout Standard
  72  
  73  Further security may be obtained by using SSL on the client and server.
  74   In the future, we may encrypt/descrypt the data on either end, or at least
  75   provide this as an option.
  76   The sessionid and key variables will make this possible, and relatively
  77   secure.
  78  \layout Subsubsection
  79  
  80  system.login
  81  \layout Standard
  82  
  83  The first request a client will make is the system.login method.
  84   Here is a sample of a server login packet in XML-RPC:
  85  \layout Code
  86  
  87  <?xml version="1.0"?>
  88  \layout Code
  89  
  90  <methodCall>
  91  \layout Code
  92  
  93  <methodName>system.login</methodName>
  94  \layout Code
  95  
  96  <params>
  97  \layout Code
  98  
  99  <param>
 100  \layout Code
 101  
 102  <value><struct>
 103  \layout Code
 104  
 105  <member><name>server_name</name>
 106  \layout Code
 107  
 108  <value><string>my.host.name</string></value>
 109  \layout Code
 110  
 111  </member>
 112  \layout Code
 113  
 114  <member><name>username</name>
 115  \layout Code
 116  
 117  <value><string>bubba</string></value>
 118  \layout Code
 119  
 120  </member>
 121  \layout Code
 122  
 123  <member><name>password</name>
 124  \layout Code
 125  
 126  <value><string>gump</string></value>
 127  \layout Code
 128  
 129  </member> </struct></value>
 130  \layout Code
 131  
 132  </param>
 133  \layout Code
 134  
 135  </params>
 136  \layout Code
 137  
 138  </methodCall>
 139  \layout Standard
 140  
 141  And the same in SOAP:
 142  \layout Code
 143  
 144  <?xml version="1.0"?>
 145  \layout Code
 146  
 147  <SOAP-ENV:Envelope
 148  \layout Code
 149  
 150  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.
 151  org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"
 152   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapi
 153  nterop.org/xsd"
 154  \layout Code
 155  
 156  xmlns:ns6="http://soapinterop.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.o
 157  rg/soap/encoding/">
 158  \layout Code
 159  
 160  <SOAP-ENV:Body> <ns6:system_login>
 161  \layout Code
 162  
 163  <server_name xsi:type=":string">my.host.name</server_name>
 164  \layout Code
 165  
 166  <username xsi:type=":string">bubba</username>
 167  \layout Code
 168  
 169  <password xsi:type=":string">gump</password>
 170  \layout Code
 171  
 172  </ns6:system_login>
 173  \layout Code
 174  
 175  </SOAP-ENV:Body>
 176  \layout Code
 177  
 178  </SOAP-ENV:Envelope>
 179  \layout Standard
 180  
 181  The same style of packet would be required for a user/client login.
 182   A successful login should yield the following reply:
 183  \layout Code
 184  
 185  <methodResponse>
 186  \layout Code
 187  
 188  <params>
 189  \layout Code
 190  
 191  <param>
 192  \layout Code
 193  
 194  <value><struct>
 195  \layout Code
 196  
 197  <member><name>sessionid</name>
 198  \layout Code
 199  
 200  <value><string>cf5c5534307562fc57915608377db007</string></value>
 201  \layout Code
 202  
 203  </member>
 204  \layout Code
 205  
 206  <member><name>kp3</name>
 207  \layout Code
 208  
 209  <value><string>2fe54daa11c8d52116788aa3f93cb70e</string></value>
 210  \layout Code
 211  
 212  </member>
 213  \layout Code
 214  
 215  </struct></value>
 216  \layout Code
 217  
 218  </param>
 219  \layout Code
 220  
 221  </params>
 222  \layout Code
 223  
 224  </methodResponse>
 225  \layout Standard
 226  
 227  And a failed login:
 228  \layout Code
 229  
 230  <methodResponse>
 231  \layout Code
 232  
 233  <params>
 234  \layout Code
 235  
 236  <param>
 237  \layout Code
 238  
 239  <value><struct>
 240  \layout Code
 241  
 242  <member><name>GOAWAY</name>
 243  \layout Code
 244  
 245  <value><string>XOXO</string></value>
 246  \layout Code
 247  
 248  </member>
 249  \layout Code
 250  
 251  </struct></value>
 252  \layout Code
 253  
 254  </param>
 255  \layout Code
 256  
 257  </params>
 258  \layout Code
 259  
 260  </methodResponse>
 261  \layout Standard
 262  
 263  eqweqw
 264  \layout Subsubsection
 265  
 266  system.logout
 267  \layout Standard
 268  
 269  Logout:
 270  \layout Code
 271  
 272  <?xml version="1.0"?>
 273  \layout Code
 274  
 275  <methodCall>
 276  \layout Code
 277  
 278  <methodName>system.logout</methodName>
 279  \layout Code
 280  
 281  <params> <param>
 282  \layout Code
 283  
 284  <value><struct>
 285  \layout Code
 286  
 287  <member><name>sessionid</name>
 288  \layout Code
 289  
 290  <value><string>ea35cac53d2c12bd05caecd97304478a</string></value>
 291  \layout Code
 292  
 293  </member>
 294  \layout Code
 295  
 296  <member><name>kp3</name>
 297  \layout Code
 298  
 299  <value><string>4f2b256e0da4e7cbbebaac9f1fc8ca4a</string></value>
 300  \layout Code
 301  
 302  </member>
 303  \layout Code
 304  
 305  </struct></value>
 306  \layout Code
 307  
 308  </param>
 309  \layout Code
 310  
 311  </params>
 312  \layout Code
 313  
 314  </methodCall>
 315  \layout Standard
 316  
 317  Logout worked:
 318  \layout Code
 319  
 320  <methodResponse>
 321  \layout Code
 322  
 323  <params>
 324  \layout Code
 325  
 326  <param>
 327  \layout Code
 328  
 329  <value><struct>
 330  \layout Code
 331  
 332  <member><name>GOODBYE</name>
 333  \layout Code
 334  
 335  <value><string>XOXO</string></value>
 336  \layout Code
 337  
 338  </member>
 339  \layout Code
 340  
 341  </struct></value>
 342  \layout Code
 343  
 344  </param>
 345  \layout Code
 346  
 347  </params>
 348  \layout Code
 349  
 350  </methodResponse>
 351  \layout Section
 352  
 353  Business layer requests
 354  \layout Standard
 355  
 356  Once a successful login return packet has been received and sessionid/kp3
 357   have been extracted, every subsequent packet sent to the egroupware server
 358   must be preceded by an Authorization header.
 359   Here is a sample header:
 360  \layout Code
 361  
 362  POST /egroupware/xmlrpc.php HTTP/1.0
 363  \layout Code
 364  
 365  User-Agent: PHP XMLRPC 1.0
 366  \layout Code
 367  
 368  Host: my.local.host
 369  \layout Code
 370  
 371  Authorization: Basic ZDgxNDIyZDRkYjg5NDEyNGNiMzZlMDhhZTdlYzAxZmY6NTU3YzkyYjBmNGE
 372  4ZDVlOTUzMzI2YmU2OTQyNjM3YjQ=
 373  \layout Code
 374  
 375  Content-Type: text/xml
 376  \layout Code
 377  
 378  Content-Length: 875
 379  \layout Standard
 380  
 381  The longish string is a base64 encoding of the $sessionid .
 382   ':' .
 383   $kp3.
 384   For now this is our only supported authentication method.
 385   Additional methods would probably also affect the methodCalls.
 386   This is certainly open to discussion.
 387   Following is a typical request for some contact data:
 388  \layout Code
 389  
 390  <?xml version="1.0"?>
 391  \layout Code
 392  
 393  <methodCall>
 394  \layout Code
 395  
 396  <methodName>addressbook.boaddressbook.read_entries</methodName>
 397  \layout Code
 398  
 399  <params>
 400  \layout Code
 401  
 402  <param>
 403  \layout Code
 404  
 405  <value><struct>
 406  \layout Code
 407  
 408  <member><name>start</name>
 409  \layout Code
 410  
 411  <value><string>1</string></value>
 412  \layout Code
 413  
 414  </member>
 415  \layout Code
 416  
 417  <member><name>limit</name>
 418  \layout Code
 419  
 420  <value><string>5</string></value>
 421  \layout Code
 422  
 423  </member>
 424  \layout Code
 425  
 426  <member><name>fields</name>
 427  \layout Code
 428  
 429  <value><struct>
 430  \layout Code
 431  
 432  <member><name>n_given</name>
 433  \layout Code
 434  
 435  <value><string>n_given</string></value>
 436  \layout Code
 437  
 438  </member>
 439  \layout Code
 440  
 441  <member><name>n_family</name>
 442  \layout Code
 443  
 444  <value><string>n_family</string></value>
 445  \layout Code
 446  
 447  </member>
 448  \layout Code
 449  
 450  </struct></value>
 451  \layout Code
 452  
 453  </member>
 454  \layout Code
 455  
 456  <member><name>query</name>
 457  \layout Code
 458  
 459  <value><string></string></value>
 460  \layout Code
 461  
 462  </member>
 463  \layout Code
 464  
 465  <member><name>filter</name>
 466  \layout Code
 467  
 468  <value><string></string></value>
 469  \layout Code
 470  
 471  </member>
 472  \layout Code
 473  
 474  <member><name>sort</name>
 475  \layout Code
 476  
 477  <value><string></string></value>
 478  \layout Code
 479  
 480  </member>
 481  \layout Code
 482  
 483  <member><name>order</name>
 484  \layout Code
 485  
 486  <value><string></string></value>
 487  \layout Code
 488  
 489  </member>
 490  \layout Code
 491  
 492  </struct></value>
 493  \layout Code
 494  
 495  </param>
 496  \layout Code
 497  
 498  </params>
 499  \layout Code
 500  
 501  </methodCall>
 502  \layout Standard
 503  
 504  Successful response:
 505  \layout Code
 506  
 507  <?xml version="1.0"?>
 508  \layout Code
 509  
 510  <methodResponse>
 511  \layout Code
 512  
 513  <params> 
 514  \layout Code
 515  
 516  <param>
 517  \layout Code
 518  
 519  <value><struct>
 520  \layout Code
 521  
 522  <member><name>0</name>
 523  \layout Code
 524  
 525  <value><struct> 
 526  \layout Code
 527  
 528  <member><name>id</name>
 529  \layout Code
 530  
 531  <value><string>1</string></value>
 532  \layout Code
 533  
 534  </member>
 535  \layout Code
 536  
 537  <member><name>lid</name>
 538  \layout Code
 539  
 540  <value><string></string></value>
 541  \layout Code
 542  
 543  </member>
 544  \layout Code
 545  
 546  <member><name>tid</name> 
 547  \layout Code
 548  
 549  <value><string>n</string></value> 
 550  \layout Code
 551  
 552  </member>
 553  \layout Code
 554  
 555  <member><name>owner</name> 
 556  \layout Code
 557  
 558  <value><string>500</string></value> 
 559  \layout Code
 560  
 561  </member>
 562  \layout Code
 563  
 564  <member><name>access</name>
 565  \layout Code
 566  
 567  <value><string>private</string></value> 
 568  \layout Code
 569  
 570  </member>
 571  \layout Code
 572  
 573  <member><name>cat_id</name> 
 574  \layout Code
 575  
 576  <value><string>1</string></value> 
 577  \layout Code
 578  
 579  </member> 
 580  \layout Code
 581  
 582  <member><name>n_given</name> 
 583  \layout Code
 584  
 585  <value><string>Alan</string></value> 
 586  \layout Code
 587  
 588  </member> 
 589  \layout Code
 590  
 591  </struct></value> 
 592  \layout Code
 593  
 594  </member> 
 595  \layout Code
 596  
 597  <member><name>1</name>
 598  \layout Code
 599  
 600  <value><struct>
 601  \layout Code
 602  
 603  <member><name>id</name>
 604  \layout Code
 605  
 606  <value><string>2</string></value>
 607  \layout Code
 608  
 609  </member>
 610  \layout Code
 611  
 612  <member><name>lid</name>
 613  \layout Code
 614  
 615  <value><string></string></value>
 616  \layout Code
 617  
 618  </member>
 619  \layout Code
 620  
 621  <member><name>tid</name>
 622  \layout Code
 623  
 624  <value><string>n</string></value>
 625  \layout Code
 626  
 627  </member>
 628  \layout Code
 629  
 630  <member><name>owner</name>
 631  \layout Code
 632  
 633  <value><string>500</string></value>
 634  \layout Code
 635  
 636  </member>
 637  \layout Code
 638  
 639  <member><name>access</name>
 640  \layout Code
 641  
 642  <value><string>private</string></value>
 643  \layout Code
 644  
 645  </member>
 646  \layout Code
 647  
 648  <member><name>cat_id</name>
 649  \layout Code
 650  
 651  <value><string>1</string></value>
 652  \layout Code
 653  
 654  </member>
 655  \layout Code
 656  
 657  <member><name>n_given</name>
 658  \layout Code
 659  
 660  <value><string>Andy</string></value>
 661  \layout Code
 662  
 663  </member>
 664  \layout Code
 665  
 666  </struct></value>
 667  \layout Code
 668  
 669  </member>
 670  \layout Code
 671  
 672  ...
 673  \layout Standard
 674  
 675  Unauthorized access attempt returns:
 676  \layout Code
 677  
 678  <methodResponse>
 679  \layout Code
 680  
 681  <params>
 682  \layout Code
 683  
 684  <param>
 685  \layout Code
 686  
 687  <value><string>UNAUTHORIZED</string></value>
 688  \layout Code
 689  
 690  </param>
 691  \layout Code
 692  
 693  </params>
 694  \layout Code
 695  
 696  </methodResponse>
 697  \layout Section
 698  
 699  More to come...
 700  \layout Standard
 701  
 702  Documenting every single call will be difficult, but should be done.
 703   In leiu of this, please see the class.bo{APPNAME}.inc.php files in each applicatio
 704  n/inc directory in the egroupware cvs.
 705   In this file will be a list_methods() function, which returns the information
 706   to the server about input/output structure for each call.
 707   If the file does not have this function, then it is not yet workable via
 708   this interface.
 709   As for the actual functions, they are also in this file.
 710   Generally, they will all accept associative array input and return same,
 711   but not always.
 712   This code is in flux, have fun.
 713  \the_end