Password-based authentication and admin-authentication support for to…

…ols/auth.py

README.md

@@ -93,6 +93,16 @@ Print the version info:
 The framework also supports Zimbra batch requests. Please refer to the class
 docs for more information.
 
+Authentication against the administration console
+-------------------------------------------------
+
+Zimbra currently doesn't support the preauth-method for authentications against
+the admin-console (URL "https://<your-zimbra-server:7071/service/admin/soap").
+
+python-zimbra's auth tool can be used to authenticate to this url by specifying
+the password instead of the preauth-key and setting the parameter admin_auth to
+True. (see API docs for specifics)
+
 Used dictionary
 ---------------
 

docs/pythonzimbra.tools.html

@@ -68,7 +68,7 @@ <h2><tt class="xref py py-mod docutils literal"><span class="pre">tools</span></
 authentication token</p>
 <dl class="function">
 <dt id="pythonzimbra.tools.auth.authenticate">
-<tt class="descclassname">pythonzimbra.tools.auth.</tt><tt class="descname">authenticate</tt><big>(</big><em>url</em>, <em>account</em>, <em>key</em>, <em>by='name'</em>, <em>expires=0</em>, <em>timestamp=None</em>, <em>timeout=None</em>, <em>request_type='xml'</em><big>)</big><a class="reference internal" href="_modules/pythonzimbra/tools/auth.html#authenticate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#pythonzimbra.tools.auth.authenticate" title="Permalink to this definition">¶</a></dt>
+<tt class="descclassname">pythonzimbra.tools.auth.</tt><tt class="descname">authenticate</tt><big>(</big><em>url</em>, <em>account</em>, <em>key</em>, <em>by='name'</em>, <em>expires=0</em>, <em>timestamp=None</em>, <em>timeout=None</em>, <em>request_type='xml'</em>, <em>admin_auth=False</em>, <em>use_password=False</em><big>)</big><a class="reference internal" href="_modules/pythonzimbra/tools/auth.html#authenticate"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#pythonzimbra.tools.auth.authenticate" title="Permalink to this definition">¶</a></dt>
 <dd><p>Authenticate to the Zimbra server</p>
 <table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
@@ -77,13 +77,21 @@ <h2><tt class="xref py py-mod docutils literal"><span class="pre">tools</span></
 <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
 <li><strong>url</strong> &#8211; URL of Zimbra SOAP service</li>
 <li><strong>account</strong> &#8211; The account to be authenticated against</li>
-<li><strong>key</strong> &#8211; The preauth key of the domain of the account</li>
+<li><strong>key</strong> &#8211; The preauth key of the domain of the account or a password (if
+admin_auth or use_password is True)</li>
 <li><strong>by</strong> &#8211; If the account is specified as a name, an ID or a
 ForeignPrincipal</li>
 <li><strong>expires</strong> &#8211; When the token expires (or 0 for default expiration)</li>
 <li><strong>timestamp</strong> &#8211; When the token was requested (None for &#8220;now&#8221;)</li>
 <li><strong>timeout</strong> &#8211; Timeout for the communication with the server. Defaults
 to the urllib2-default</li>
+<li><strong>request_type</strong> &#8211; Which type of request to use (&#8220;xml&#8221; (default) or
+&#8220;json&#8221;)</li>
+<li><strong>admin_auth</strong> &#8211; This request should authenticate and generate an admin
+token. The &#8220;key&#8221;-parameter therefore holds the admin password (implies
+use_password)</li>
+<li><strong>use_password</strong> &#8211; The &#8220;key&#8221;-parameter holds a password. Do a password-
+based user authentication.</li>
 </ul>
 </td>
 </tr>

pythonzimbra/tools/auth.py

@@ -13,27 +13,38 @@
 
 
 def authenticate(url, account, key, by='name', expires=0, timestamp=None,
-                 timeout=None, request_type="xml"):
+                 timeout=None, request_type="xml", admin_auth=False,
+                 use_password=False):
 
     """ Authenticate to the Zimbra server
 
     :param url: URL of Zimbra SOAP service
     :param account: The account to be authenticated against
-    :param key: The preauth key of the domain of the account
+    :param key: The preauth key of the domain of the account or a password (if
+      admin_auth or use_password is True)
     :param by: If the account is specified as a name, an ID or a
       ForeignPrincipal
     :param expires: When the token expires (or 0 for default expiration)
     :param timestamp: When the token was requested (None for "now")
     :param timeout: Timeout for the communication with the server. Defaults
       to the urllib2-default
+    :param request_type: Which type of request to use ("xml" (default) or
+      "json")
+    :param admin_auth: This request should authenticate and generate an admin
+      token. The "key"-parameter therefore holds the admin password (implies
+      use_password)
+    :param use_password: The "key"-parameter holds a password. Do a password-
+      based user authentication.
     :return: The authentication token
     :rtype: str or None or unicode
     """
 
     if timestamp is None:
         timestamp = int(datetime.now().strftime("%s")) * 1000
 
-    pak = preauth.create_preauth(account, key, by, expires, timestamp)
+    pak = ""
+    if not admin_auth:
+        pak = preauth.create_preauth(account, key, by, expires, timestamp)
 
     if request_type == 'xml':
 
@@ -43,20 +54,39 @@ def authenticate(url, account, key, by='name', expires=0, timestamp=None,
 
         auth_request = RequestJson()
 
+    request_data = {
+        'account': {
+            'by': by,
+            '_content': account
+        }
+    }
+
+    ns = "urn:zimbraAccount"
+
+    if admin_auth:
+
+        ns = "urn:zimbraAdmin"
+
+        request_data['password'] = key
+
+    elif use_password:
+
+        request_data['password'] = {
+            "_content": key
+        }
+
+    else:
+
+        request_data['preauth'] = {
+            'timestamp': timestamp,
+            'expires': expires,
+            '_content': pak
+        }
+
     auth_request.add_request(
         'AuthRequest',
-        {
-            'account': {
-                'by': by,
-                '_content': account
-            },
-            'preauth': {
-                'timestamp': timestamp,
-                'expires': expires,
-                '_content': pak
-            }
-        },
-        'urn:zimbraAccount'
+        request_data,
+        ns
     )
 
     server = Communication(url, timeout)

sphinx/conf.py

@@ -16,7 +16,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration -----------------------------------------------------
 

sphinx/update_docs.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+cd ..
+sphinx-build sphinx docs