Add get user by email method to duo_client_python along with example …

…script (#244)

* doc: add report_user_by_email.py to examples

* feat: add get_user_by_email() method to admin.py
doc: add report_user_by_email.py to examples

* Revert "feat: add get_user_by_email() method to admin.py"

This reverts commit 48580c1.

* feat: add get_user_by_email() method to admin.py
doc: add report_user_by_email.py to examples

duo_client/admin.py

@@ -728,6 +728,24 @@ def get_user_by_id(self, user_id):
         response = self.json_api_call('GET', path, {})
         return response
 
+    def get_user_by_email(self, email):
+        """
+        Returns user specified by email.
+
+        email - User to fetch
+
+        Returns user object.
+
+        Raises RuntimeError on error.
+        """
+        params = {
+            'email': email,
+        }
+        response = self.json_api_call('GET',
+                                      '/admin/v1/users',
+                                      params)
+        return response
+
     def get_users_by_name(self, username):
         """
         Returns user specified by username.

examples/report_user_by_email.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+
+""" Script to illustrate how to retrieve a user from the Duo Admin API using the associated email address"""
+
+from __future__ import absolute_import, print_function
+import sys
+import getpass
+from pprint import pprint
+
+import duo_client
+from six.moves import input
+
+argv_iter = iter(sys.argv[1:])
+
+
+def get_next_arg(prompt, secure=False):
+    """Read information from STDIN, using getpass when sensitive information should not be echoed to tty"""
+    try:
+        return next(argv_iter)
+    except StopIteration:
+        if secure is True:
+            return getpass.getpass(prompt)
+        else:
+            return input(prompt)
+
+
+def main():
+    """ Primary script execution code """
+    # Configuration and information about objects to create.
+    admin_api = duo_client.Admin(
+            ikey=get_next_arg('Admin API integration key ("DI..."): '),
+            skey=get_next_arg('integration secret key: ', secure=True),
+            host=get_next_arg('API hostname ("api-....duosecurity.com"): '),
+    )
+
+    # Retrieve user info from API:
+    email_address = get_next_arg('E-mail address of user to retrieve: ')
+    req_params = {"email": email_address}
+    # There is no get_user_by_email in the duo_client_python library, so we use the generic api_call
+    user = admin_api.json_api_call(
+            method='GET',
+            path='/admin/v1/users',
+            params=req_params
+    )
+
+    if user:
+        pprint(user, indent=2)
+    else:
+        print(f"User with email [{email_address}] could not be found.")
+
+
+if __name__ == '__main__':
+    main()