Support Portal Active Directory conn. mgmt. (#132)

* Support Portal Active Directory conn. mgmt.

Author: saimonation

cterasdk/core/directoryservice.py

@@ -3,14 +3,178 @@
 from .base_command import BaseCommand
 from ..common import Object
 from ..exception import CTERAException
-from .enum import PortalAccountType, SearchType
+from .enum import PortalAccountType, SearchType, DirectoryServiceType, DirectoryServiceFetchMode, Role, DirectorySearchEntityType
+from .types import AccessControlEntry, AccessControlRule, UserAccount, GroupAccount
 
 
 class DirectoryService(BaseCommand):
     """
     Portal Active Directory APIs
     """
 
+    def _get_configuration(self):
+        return self._portal.get('/directoryConnector')
+
+    def connected(self):
+        directory_services_config = self._get_configuration()
+        if directory_services_config is None:
+            return False
+        try:
+            self._connect_to_directory_services(directory_services_config)
+            return True
+        except CTERAException:
+            return False
+
+    # pylint: disable=too-many-arguments
+    def connect(self, domain, username, password, directory=DirectoryServiceType.Microsoft,
+                domain_controllers=None, ou=None, ssl=False, krb=False, mapping=None, acl=None,
+                default=Role.Disabled, fetch=DirectoryServiceFetchMode.Lazy):
+        """
+        Connect a Portal tenant to directory services
+
+        :param str domain: The directory services domain to connect to
+        :param str username: The user name to use when connecting to the active directory services
+        :param str password: The password to use when connecting to the active directory services
+        :param str,optional ou: The OU path to use when connecting to the active directory services, defaults to `None`
+        :param cterasdk.core.enum.DirectoryServiceType,optional directory: The directory service type, deafults to `'ActiveDirectory'`
+        :param cterasdk.core.types.DomainControllers,optional domain_controllers:
+            Connect to a primary and a secondary domain controllers, defaults to `None`
+        :param bool,optional ssl: Connect using SSL, defaults to `False`
+        :param bool,optional krb: Connect using Kerberos, defaults to `False`
+        :param list[cterasdk.core.types.ADDomainIDMapping],optional: The directory services UID/GID mapping
+        :param list[cterasdk.core.types.AccessControlEntry],optional acl: List of access control entries and their associated roles
+        :param cterasdk.core.enum.Role default: Default role if no match applies, defaults to `None`
+        :param str,optional fetch: Configure identity fetching mode, defaults to `'Lazy'`
+        """
+        param = Object()
+        param._classname = 'ActiveDirectory'  # pylint: disable=protected-access
+        param.type = directory
+        param.domain = domain
+        param.useKerberos = krb
+        param.useSSL = ssl
+        param.username = username
+        param.password = password
+        param.ou = ou
+        param.noMatchRole = default
+        param.accessControlRules = None
+        param.idMapping = None
+        param.fetchMode = fetch
+
+        if domain_controllers:
+            param.ipAddresses = Object()
+            param.ipAddresses._classname = 'DomainControlIPAddresses'  # pylint: disable=protected-access
+            param.ipAddresses.ipAddress1 = domain_controllers.primary
+            param.ipAddresses.ipAddress2 = domain_controllers.secondary
+
+        tenant = self._portal.session().user.tenant
+        logging.getLogger().info('Connecting Portal to directory services. %s', {
+            'tenant': tenant,
+            'type': type,
+            'domain': domain
+        })
+        self._connect_to_directory_services(param)
+        logging.getLogger().info('Connected Portal to directory services. %s', {'tennat': tenant, 'domain': domain})
+
+        if mapping:
+            self._configure_advanced_mapping(mapping)
+
+        if acl:
+            self._configure_access_control(acl, default)
+
+    def _connect_to_directory_services(self, param):
+        return self._portal.execute('', 'testAndSaveAD', param)
+
+    def get_advanced_mapping(self):
+        """
+        Retrieve directory services advanced mapping configuration
+
+        :returns: A dictionary of domain mapping objects
+        :rtype: dict
+        """
+        return {map.domainFlatName: map for map in self._portal.get('/directoryConnector/idMapping/map')}
+
+    def set_advanced_mapping(self, mapping):
+        """
+        Configure advanced mapping
+
+        :param list[cterasdk.core.types.ADDomainIDMapping] mapping: The directory services UID/GID mapping
+        """
+        if self._get_configuration() is None:
+            raise CTERAException('Failed to apply mapping. Not connected to directory services.')
+
+        return self._configure_advanced_mapping(mapping)
+
+    def _configure_advanced_mapping(self, mapping):
+        param = Object()
+        param._classname = 'ADIDMapping'  # pylint: disable=protected-access
+        param.map = mapping
+        logging.getLogger().debug('Updating advanced mapping. %s', {
+            'domains': [mapping.domainFlatName for mapping in param.map]
+        })
+        response = self._portal.put('/directoryConnector/idMapping', param)
+        logging.getLogger().info('Updated advanced mapping.')
+        return response
+
+    def get_access_control(self):
+        """
+        Retrieve directory services access control list
+
+        :returns: List of access control entries
+        :rtype: list[cterasdk.core.types.AccessControlEntry]
+        """
+        acl = []
+        for ace in self._portal.get('/directoryConnector/accessControlRules'):
+            if ace.group.type == DirectorySearchEntityType.User:
+                acl.append(AccessControlEntry(UserAccount(ace.group.name, ace.group.domain), ace.role))
+            elif ace.group.type == DirectorySearchEntityType.Group:
+                acl.append(AccessControlEntry(GroupAccount(ace.group.name, ace.group.domain), ace.role))
+        return acl
+
+    def set_access_control(self, acl=None, default=None):
+        """
+        Configure directory services access control
+
+        :param list[cterasdk.core.types.AccessControlEntry],optional acl:
+            List of access control entries and their associated roles
+        :param cterasdk.core.enum.Role default: Default role if no match applies, defaults to `None`
+        """
+        directory_services_config = self._get_configuration()
+        if directory_services_config is None:
+            raise CTERAException('Failed to apply access control. Not connected to directory services.')
+
+        default = default if default is not None else directory_services_config.noMatchRole
+        return self._configure_access_control(acl, default)
+
+    def _configure_access_control(self, acl, default=None):
+
+        access_control_rules = list()
+        for ace in acl:
+            account = None
+            if ace.account.account_type == PortalAccountType.User:
+                account = self._search_users(ace.account.directory, ace.account.name)
+            elif ace.account.account_type == PortalAccountType.Group:
+                account = self._search_groups(ace.account.directory, ace.account.name)
+            access_control_rules.append(AccessControlRule(account, ace.role))
+
+        logging.getLogger().info('Updating access control rules.')
+        response = self._portal.put('/directoryConnector/accessControlRules', access_control_rules)
+        logging.getLogger().info('Updated access control rules.')
+
+        if default is not None:
+            logging.getLogger().info('Updating default role.')
+            response = self._portal.put('/directoryConnector/noMatchRole', default)
+            logging.getLogger().info('Updated default role')
+
+        return response
+
+    def domains(self):
+        """
+        Get domains
+
+        :return list(str): List of names of all discovered domains
+        """
+        return self._portal.execute('', 'getADTrustedDomains', False)
+
     def fetch(self, active_directory_accounts):
         """
         Instruct the Portal to fetch the provided Active Directory Accounts
@@ -39,9 +203,7 @@ def fetch(self, active_directory_accounts):
                 param.append(self._search_groups(active_directory_account.directory, active_directory_account.name))
 
         logging.getLogger().info('Starting to fetch users and groups.')
-
         response = self._portal.execute('', 'syncAD', param)
-
         logging.getLogger().info('Started fetching users and groups.')
 
         return response
@@ -80,9 +242,15 @@ def _search_directory_services(self, search_type, domain, name):
                 return principal
 
         raise CTERAException(
-            'Search returned multiple results, but none that match your search criteria',
+            'Search returned multiple results, but none matches your search criteria',
             None,
             domain=domain,
             type=search_type,
             account=name
         )
+
+    def disconnect(self):
+        """
+        Disconnect a Portal tenant from directory services
+        """
+        return self._portal.put('/directoryConnector', None)

cterasdk/core/enum.py

@@ -504,3 +504,38 @@ class Mode:
     """
     Enabled = "enabled"
     Disabled = "disabled"
+
+
+class DirectoryServiceType:
+    """
+    Directory Service Type
+
+    :ivar str Microsoft: Active Directory
+    :ivar str LDAP: LDAP
+    :ivar str Apple: Apple Open Directory
+    """
+    Microsoft = 'ActiveDirectory'
+    LDAP = 'LDAP'
+    Apple = 'AppleOpenDirectory'
+
+
+class DirectoryServiceFetchMode:
+    """
+    Directory Service Fetch Mode
+
+    :ivar str Eager: Eager
+    :ivar str Lazy: Lazy
+    """
+    Eager = 'Eager'
+    Lazy = 'Lazy'
+
+
+class DirectorySearchEntityType:
+    """
+    Directory Search Entity Type
+
+    :ivar str User: User
+    :ivar str Group: Group
+    """
+    User = 'user'
+    Group = 'group'

cterasdk/core/types.py

@@ -17,6 +17,12 @@
 PlatformVersion.version.__doc__ = 'The version identifier'
 
 
+AccessControlEntry = namedtuple('AccessControlEntry', ('account', 'role'))
+AccessControlEntry.__doc__ = 'Tuple holding a Portal account and its respective permission'
+AccessControlEntry.account.__doc__ = 'The Portal group or user account'
+AccessControlEntry.role.__doc__ = 'The group or user role'
+
+
 class PortalAccount(ABC):
     """
     Base Class for Portal Account
@@ -393,3 +399,41 @@ def to_server_object(self):
         param.httpsOnly = self.https
         param.directUpload = self.direct
         return param
+
+
+class DomainControllers:
+
+    def __init__(self, primary=None, secondary=None):
+        self._primary = primary
+        self._secondary = secondary
+
+    @property
+    def primary(self):
+        return self._primary
+
+    @property
+    def secondary(self):
+        return self._secondary
+
+
+class AccessControlRule(Object):
+
+    def __init__(self, group, role):
+        self._classname = 'AccessControlRule'
+        self.group = group
+        self.role = role
+
+
+class ADDomainIDMapping(Object):
+    """
+    Base Class for Directory Service ID Mapping
+
+    :ivar str domain: The domain flat name
+    :param int start: The minimum id to use for mapping
+    :param int end: The maximum id to use for mapping
+    """
+    def __init__(self, domain, start, end):
+        self._classname = 'ADDomainIDMapping'
+        self.domainFlatName = domain
+        self.minID = start
+        self.maxID = end

cterasdk/edge/directoryservice.py

@@ -92,8 +92,8 @@ def advanced_mapping(self, domain, start, end):
         Configure advanced mapping
 
         :param str domain: The active directory domain
-        :param str start: The minimum id to use for mapping
-        :param str end: The maximum id to use for mapping
+        :param int start: The minimum id to use for mapping
+        :param int end: The maximum id to use for mapping
         """
         mappings = self._gateway.get('/config/fileservices/cifs/idMapping/map')
         for mapping in mappings: