[#426][#428][#429] groupadmin capabilities update

The Python client now provides:
   * [426][428] the complete capabilities offered in "igroupadmin", including
     mkgroup, atg, rfg, and mkuser.
   * [429] "session.groups" as a synonym for "session.user_groups" -- the latter now being
     deprecated. (Accordingly, we rename "UserGroup" to simply "Group" where used in class names.)

Author: d-w-moore

README.rst

@@ -1064,9 +1064,9 @@ Listing Users and Groups ; calculating Group Membership
 iRODS tracks groups and users using two tables, R_USER_MAIN and R_USER_GROUP.
 Under this database schema, all "user groups" are also users:
 
->>> from irods.models import User, UserGroup
+>>> from irods.models import User, Group
 >>> from pprint import pprint
->>> pprint(list( [ (x[User.id], x[User.name]) for x in session.query(User) ] ))
+>>> pprint(list((x[User.id], x[User.name]) for x in session.query(User)))
 [(10048, 'alice'),
  (10001, 'rodsadmin'),
  (13187, 'bobby'),
@@ -1083,20 +1083,20 @@ user ID that iRODS internally recognizes as a "Group":
 >>> [x[User.name] for x in groups]
 ['collab', 'public', 'rodsadmin', 'empty']
 
-Since we can instantiate iRODSUserGroup and iRODSUser objects directly from the rows of
+Since we can instantiate iRODSGroup and iRODSUser objects directly from the rows of
 a general query on the corresponding tables,  it is also straightforward to trace out
 the groups' memberships:
 
->>> from irods.user import iRODSUser, iRODSUserGroup
->>> grp_usr_mapping = [ (iRODSUserGroup ( session.user_groups, result), iRODSUser (session.users, result)) \
-...                     for result in session.query(UserGroup,User) ]
+>>> from irods.user import iRODSUser, iRODSGroup
+>>> grp_usr_mapping = [ (iRODSGroup(session.groups, result), iRODSUser(session.users, result)) \
+...                     for result in session.query(Group,User) ]
 >>> pprint( [ (x,y) for x,y in grp_usr_mapping if x.id != y.id ] )
-[(<iRODSUserGroup 10045 collab>, <iRODSUser 10048 alice rodsuser tempZone>),
- (<iRODSUserGroup 10001 rodsadmin>, <iRODSUser 10003 rods rodsadmin tempZone>),
- (<iRODSUserGroup 10002 public>, <iRODSUser 10003 rods rodsadmin tempZone>),
- (<iRODSUserGroup 10002 public>, <iRODSUser 10048 alice rodsuser tempZone>),
- (<iRODSUserGroup 10045 collab>, <iRODSUser 13187 bobby rodsuser tempZone>),
- (<iRODSUserGroup 10002 public>, <iRODSUser 13187 bobby rodsuser tempZone>)]
+[(<iRODSGroup 10045 collab>, <iRODSUser 10048 alice rodsuser tempZone>),
+ (<iRODSGroup 10001 rodsadmin>, <iRODSUser 10003 rods rodsadmin tempZone>),
+ (<iRODSGroup 10002 public>, <iRODSUser 10003 rods rodsadmin tempZone>),
+ (<iRODSGroup 10002 public>, <iRODSUser 10048 alice rodsuser tempZone>),
+ (<iRODSGroup 10045 collab>, <iRODSUser 13187 bobby rodsuser tempZone>),
+ (<iRODSGroup 10002 public>, <iRODSUser 13187 bobby rodsuser tempZone>)]
 
 (Note that in general queries, fields cannot be compared to each other, only to literal constants; thus
 the '!=' comparison in the Python list comprehension.)
@@ -1108,6 +1108,24 @@ users (those whose User.type is 'rodsadmin' or 'rodsuser'). The empty group ('em
 members, so it doesn't show up in our final list.
 
 
+Group Administrator Capabilities
+--------------------------------
+With v1.1.7, PRC acquires the full range of abilities possessed by the igroupadmin command.
+
+Firstly, a groupadmin may invoke methods to create groups, and may add users to, or remove them from, any
+group to which they themselves belong:
+
+>>> session.groups.create('lab')
+>>> session.groups.addmember('lab',session.username)  # allow self to administer group
+>>> session.groups.addmember('lab','otheruser')
+>>> session.groups.removemember('lab','otheruser')
+
+In addition, a groupadmin may also create accounts for new users and enable their logins by initializing
+a native password for them:
+
+>>> session.users.create_with_password('alice', 'change_me')
+
+
 iRODS Permissions (ACLs)
 ------------------------
 

irods/exception.py

@@ -39,9 +39,11 @@ class UserDoesNotExist(DoesNotExist):
     pass
 
 
-class UserGroupDoesNotExist(DoesNotExist):
+class GroupDoesNotExist(DoesNotExist):
     pass
 
+# NOTE: Everything of the form *UserGroup* is deprecated.
+UserGroupDoesNotExist = GroupDoesNotExist
 
 class ResourceDoesNotExist(DoesNotExist):
     pass

irods/manager/user_manager.py

@@ -1,13 +1,14 @@
 from __future__ import absolute_import
 import logging
 import os
+import warnings
 
-from irods.models import User, UserGroup
+from irods.models import User, Group
 from irods.manager import Manager
 from irods.message import UserAdminRequest, GeneralAdminRequest, iRODSMessage, GetTempPasswordForOtherRequest, GetTempPasswordForOtherOut
-from irods.exception import UserDoesNotExist, UserGroupDoesNotExist, NoResultFound, CAT_SQL_ERR
+from irods.exception import UserDoesNotExist, GroupDoesNotExist, NoResultFound, CAT_SQL_ERR
 from irods.api_number import api_number
-from irods.user import iRODSUser, iRODSUserGroup
+from irods.user import iRODSUser, iRODSGroup
 import irods.password_obfuscation as obf
 
 logger = logging.getLogger(__name__)
@@ -27,6 +28,24 @@ def get(self, user_name, user_zone=""):
             raise UserDoesNotExist()
         return iRODSUser(self, result)
 
+    def create_with_password(self, user_name, password, user_zone = ''):
+        """This method can be used by a groupadmin to initialize the password field while creating the new user.
+           (This is necessary since group administrators may not change the password of an existing user.)
+        """
+
+        message_body = UserAdminRequest(
+                "mkuser", user_name, "" if not password else \
+                                     obf.obfuscate_new_password_with_key(password, self.sess.pool.account.password)
+                )
+        request = iRODSMessage("RODS_API_REQ", msg=message_body,
+                               int_info=api_number['USER_ADMIN_AN'])
+        with self.sess.pool.get_connection() as conn:
+            conn.send(request)
+            response = conn.recv()
+        logger.debug(response.int_info)
+        return self.get(user_name, user_zone)
+
+
     def create(self, user_name, user_type, user_zone="", auth_str=""):
         message_body = GeneralAdminRequest(
             "add",
@@ -176,36 +195,60 @@ def modify(self, user_name, option, new_value, user_zone=""):
         logger.debug(response.int_info)
 
 
-class UserGroupManager(UserManager):
+class GroupManager(UserManager):
 
     def get(self, name, user_zone=""):
-        query = self.sess.query(UserGroup).filter(UserGroup.name == name)
+        query = self.sess.query(Group).filter(Group.name == name)
 
         try:
             result = query.one()
         except NoResultFound:
-            raise UserGroupDoesNotExist()
-        return iRODSUserGroup(self, result)
+            raise GroupDoesNotExist()
+        return iRODSGroup(self, result)
 
-    def create(self, name, user_type='rodsgroup', user_zone="", auth_str="", group_admin=False):
-        if group_admin:
-            message_body = UserAdminRequest(
+    def _api_info(self, group_admin_flag):
+        """
+        If group_admin_flag is:         then use UserAdminRequest API:
+        ---------------------------     ------------------------------
+        True                            always
+        False (user_groups default)     never
+        None  (groups default)          when user type is groupadmin
+        """
+
+        sess = self.sess
+        if group_admin_flag or (group_admin_flag is not False and sess.users.get(sess.username).type == 'groupadmin'):
+            return (UserAdminRequest, 'USER_ADMIN_AN')
+        return (GeneralAdminRequest, 'GENERAL_ADMIN_AN')
+
+    def create(self, name,
+               user_type = 'rodsgroup',
+               user_zone = "",
+               auth_str = "",
+               group_admin = False, **options):
+
+        if not options.pop('suppress_deprecation_warning', False):
+            warnings.warn('Use of session.user_groups is deprecated in v1.1.7 - prefer session.groups',
+                          DeprecationWarning, stacklevel = 2)
+
+        (MessageClass, api_key) = self._api_info(group_admin)
+        api_to_use = api_number[api_key]
+
+        if MessageClass is UserAdminRequest:
+            message_body = MessageClass(
                 "mkgroup",
                 name,
                 user_type,
                 user_zone
             )
-            api_to_use = api_number['USER_ADMIN_AN']
         else:
-            message_body = GeneralAdminRequest(
+            message_body = MessageClass(
                 "add",
                 "user",
                 name,
                 user_type,
                 "",
                 ""
             )
-            api_to_use = api_number['GENERAL_ADMIN_AN']
         request = iRODSMessage("RODS_API_REQ", msg=message_body,
                                int_info=api_to_use)
         with self.sess.pool.get_connection() as conn:
@@ -216,11 +259,21 @@ def create(self, name, user_type='rodsgroup', user_zone="", auth_str="", group_a
 
     def getmembers(self, name):
         results = self.sess.query(User).filter(
-            User.type != 'rodsgroup', UserGroup.name == name)
+            User.type != 'rodsgroup', Group.name == name)
         return [iRODSUser(self, row) for row in results]
 
-    def addmember(self, group_name, user_name, user_zone=""):
-        message_body = GeneralAdminRequest(
+    def addmember(self, group_name,
+                        user_name,
+                        user_zone = "",
+                        group_admin = False, **options):
+
+        if not options.pop('suppress_deprecation_warning', False):
+            warnings.warn('Use of session.user_groups is deprecated in v1.1.7 - prefer session.groups',
+                          DeprecationWarning, stacklevel = 2)
+
+        (MessageClass, api_key) = self._api_info(group_admin)
+
+        message_body = MessageClass(
             "modify",
             "group",
             group_name,
@@ -229,14 +282,25 @@ def addmember(self, group_name, user_name, user_zone=""):
             user_zone
         )
         request = iRODSMessage("RODS_API_REQ", msg=message_body,
-                               int_info=api_number['GENERAL_ADMIN_AN'])
+                               int_info=api_number[api_key])
         with self.sess.pool.get_connection() as conn:
             conn.send(request)
             response = conn.recv()
         logger.debug(response.int_info)
 
-    def removemember(self, group_name, user_name, user_zone=""):
-        message_body = GeneralAdminRequest(
+    def removemember(self,
+                     group_name,
+                     user_name,
+                     user_zone = "",
+                     group_admin = False, **options):
+
+        if not options.pop('suppress_deprecation_warning', False):
+            warnings.warn('Use of session.user_groups is deprecated in v1.1.7 - prefer session.groups',
+                          DeprecationWarning, stacklevel = 2)
+
+        (MessageClass, api_key) = self._api_info(group_admin)
+
+        message_body = MessageClass(
             "modify",
             "group",
             group_name,
@@ -245,8 +309,12 @@ def removemember(self, group_name, user_name, user_zone=""):
             user_zone
         )
         request = iRODSMessage("RODS_API_REQ", msg=message_body,
-                               int_info=api_number['GENERAL_ADMIN_AN'])
+                               int_info=api_number[api_key])
         with self.sess.pool.get_connection() as conn:
             conn.send(request)
             response = conn.recv()
         logger.debug(response.int_info)
+
+
+# NOTE: Everything of the form *UserGroup* is deprecated.
+UserGroupManager = GroupManager

irods/models.py

@@ -66,9 +66,12 @@ class CollectionUser(Model):
     zone = Column(String, 'COL_COLL_USER_ZONE', 1301)
 
 
-class UserGroup(Model):
+class Group(Model):
     id = Column(Integer, 'USER_GROUP_ID', 900)
     name = Column(String, 'USER_GROUP_NAME', 901)
+ 
+# The UserGroup model-class is now renamed Group, but we'll keep the deprecated name around for now.
+UserGroup = Group
 
 
 class Resource(Model):

irods/password_obfuscation.py

@@ -288,6 +288,15 @@ def scramble_v2(s, first_key, second_key):
 
     return scramble(to_scramble, key=hashed_key, scramble_prefix='', block_chaining=True)
 
+def obfuscate_new_password_with_key(new_password, obfuscation_key):
+    lcopy = MAX_PASSWORD_LENGTH - 10 - len(new_password)
+    new_password = new_password[:MAX_PASSWORD_LENGTH]
+    if lcopy > 15:
+        # https://github.com/irods/irods/blob/4.2.1/plugins/database/src/db_plugin.cpp#L1094-L1095
+        padding = '1gCBizHWbwIYyWLoysGzTe6SyzqFKMniZX05faZHWAwQKXf6Fs'
+        new_password += padding[:lcopy]
+    return scramble(new_password, obfuscation_key, scramble_prefix='')
+
 # port of https://github.com/irods/irods_client_icommands/blob/4.2.1/src/iadmin.cpp#L878-L930
 def obfuscate_new_password(new, old, signature):
     pwd_len = len(new)

irods/session.py

@@ -12,7 +12,7 @@
 from irods.manager.data_object_manager import DataObjectManager
 from irods.manager.metadata_manager import MetadataManager
 from irods.manager.access_manager import AccessManager
-from irods.manager.user_manager import UserManager, UserGroupManager
+from irods.manager.user_manager import UserManager, GroupManager
 from irods.manager.resource_manager import ResourceManager
 from irods.manager.zone_manager import ZoneManager
 from irods.exception import NetworkException
@@ -67,6 +67,51 @@ def available_permissions(self):
             self.__access = _iRODSAccess_pre_4_3_0 if self.server_version < (4,3) else iRODSAccess
         return self.__access
 
+    @property
+    def groups(self):
+        class _GroupManager(self.user_groups.__class__):
+
+            def create(self, name,
+                             group_admin = None): # NB new default (see user_groups manager and i/f, with False as default)
+
+                user_type = 'rodsgroup'   # These are no longer parameters in the new interface, as they have no reason to vary.
+                user_zone = ""            # Groups (1) are always of type 'rodsgroup', (2) always belong to the local zone, and
+                auth_str = ""             #        (3) do not authenticate.
+
+                return super(_GroupManager, self).create(name,
+                                                         user_type,
+                                                         user_zone,
+                                                         auth_str,
+                                                         group_admin,
+                                                         suppress_deprecation_warning = True)
+
+            def addmember(self, group_name,
+                                user_name,
+                                user_zone = "",
+                                group_admin = None):
+
+                return super(_GroupManager, self).addmember(group_name,
+                                                            user_name,
+                                                            user_zone,
+                                                            group_admin,
+                                                            suppress_deprecation_warning = True)
+
+            def removemember(self, group_name,
+                                   user_name,
+                                   user_zone = "",
+                                   group_admin = None):
+
+                return super(_GroupManager, self).removemember(group_name,
+                                                               user_name,
+                                                               user_zone,
+                                                               group_admin,
+                                                               suppress_deprecation_warning = True)
+
+        _groups = getattr(self,'_groups',None)
+        if not _groups:
+            _groups = self._groups = _GroupManager(self.user_groups.sess)
+        return self._groups
+
     @property
     def acls(self):
         class ACLs(self.permissions.__class__):
@@ -95,7 +140,7 @@ def __init__(self, configure = True, auto_cleanup = True, **kwargs):
         self.metadata = MetadataManager(self)
         self.permissions = AccessManager(self)
         self.users = UserManager(self)
-        self.user_groups = UserGroupManager(self)
+        self.user_groups = GroupManager(self)
         self.resources = ResourceManager(self)
         self.zones = ZoneManager(self)
 

irods/test/access_test.py

@@ -249,10 +249,10 @@ def test_raw_acls__207(self):
         data = helpers.make_object(self.sess,"/".join((self.coll_path,"test_obj")))
         eg = eu = fg = fu = None
         try:
-            eg = self.sess.user_groups.create ('egrp')
+            eg = self.sess.groups.create ('egrp')
             eu = self.sess.users.create ('edith','rodsuser')
             eg.addmember(eu.name,eu.zone)
-            fg = self.sess.user_groups.create ('fgrp')
+            fg = self.sess.groups.create ('fgrp')
             fu = self.sess.users.create ('frank','rodsuser')
             fg.addmember(fu.name,fu.zone)
             my_ownership = set([('own', self.sess.username, self.sess.zone)])
@@ -283,7 +283,7 @@ def test_ses_acls_data_and_collection_395_396(self):
 
             self.alice = ses.users.create('alice','rodsuser')
             self.bob = ses.users.create('bob','rodsuser')
-            self.team = ses.user_groups.create('team')
+            self.team = ses.groups.create('team')
             self.team.addmember('bob')
             ses.users.modify('bob', 'password', 'bpass')