Merge branch 'v2' into v2-sign-phase-2

Author: adorton-adobe

docs/en/user-manual/advanced_configuration.md

@@ -169,6 +169,44 @@ group name. Join them with "::". For example:
     - "d37::Special Ops Group"
 ```
 
+### ESM Secondary Targets
+
+Organizations with Enterprise Storage Model (ESM) enabled handle users differently from traditional User Storage Model (USM) organizations.
+ESM organizations use Business IDs instead of Adobe IDs. Business IDs are special accounts that govern a user's profile for a specific
+organization. Business IDs do not directly provide authentication capabilities for users. Instead, each is linked to an Adobe ID,
+Enterprise ID or Federated ID that handles authentication.
+
+The nature of Business IDs creates unique behavior in ESM organizations that have a trust with an existing user directory. Users
+with a domain belonging to the directory will always be created as Business ID instead of the actual user type (Federated or Enterprise,
+depending on directory settings).
+
+For example, if we have a Federated directory with a claim on `example.com`, and we create a new user in the ESM trustee
+(e.g. `[email protected]`), then that user will be a Business ID in the trustee console and not Federate. The user will
+still use the configured Identity Provider to authenticate.
+
+When syncing to secondary ESM targets, this feature prevents the UST from fully managing Business ID users on trustee consoles.
+When performing user sync on secondary targets, the UST expects the identity types between users on parent and child to match.
+
+To manage Business IDs as their linked identity type, enable the `uses_business_id` option in the secondary target's UMAPI
+connector config file.
+
+```yaml
+# connector-umapi-org2.yml
+server:
+  host: usermanagement.adobe.io
+  ims_host: ims-na1.adobelogin.com
+enterprise:
+  org_id: xxx@AdobeOrg
+  client_secret: xxx
+  priv_key_path: private-org2.key
+  client_id: xxx
+  tech_acct_id: [email protected]
+uses_business_id: True
+```
+
+This essentially overrides the Business ID user type to the type of the user from the primary target, ensuring that
+the full user lifecycle of the user on the secondary target is managed.
+
 ## Custom Attributes and Mappings
 
 It is possible to define custom mappings of directory attribute

tests/test_config.py

@@ -1,6 +1,10 @@
 import pytest
 
 import user_sync.engine.umapi
+import yaml
+import shutil
+from user_sync.connector.connector_umapi import UmapiConnector
+from user_sync.config import ConfigFileLoader, ConfigLoader, DictConfig
 from user_sync import flags
 from user_sync.config.common import ConfigFileLoader, DictConfig
 from user_sync.config.user_sync import UMAPIConfigLoader
@@ -174,5 +178,45 @@ def test_shell_exec_flag(test_resources, modify_root_config, cli_args, monkeypat
 
         args = cli_args({'config_filename': root_config_file})
         modify_root_config(['directory_users', 'connectors', 'ldap'], "$(some command)")
-        with pytest.raises(AssertionException):
-            UMAPIConfigLoader(args)
+        config_loader = ConfigLoader(args)
+
+        directory_connector_module_name = config_loader.get_directory_connector_module_name()
+        if directory_connector_module_name is not None:
+            directory_connector = DirectoryConnector()
+            with pytest.raises(AssertionException):
+                config_loader.get_directory_connector_options(directory_connector.name)
+
+
+def test_uses_business_id_true(tmp_config_files, modify_umapi_config, cli_args, private_key):
+    root_config, _, _ = tmp_config_files
+    modify_umapi_config(['uses_business_id'], True)
+    modify_umapi_config(['enterprise', 'priv_key_path'], private_key)
+    args = cli_args({'config_filename': root_config})
+    config_loader = ConfigLoader(args)
+    connector_options, _ = config_loader.get_umapi_options()
+    UmapiConnector.create_conn = False
+    umapi_connector = UmapiConnector('.primary', connector_options)
+    assert umapi_connector.uses_business_id
+
+
+def test_uses_business_id_false(tmp_config_files, modify_umapi_config, cli_args, private_key):
+    root_config, _, _ = tmp_config_files
+    modify_umapi_config(['uses_business_id'], False)
+    modify_umapi_config(['enterprise', 'priv_key_path'], private_key)
+    args = cli_args({'config_filename': root_config})
+    config_loader = ConfigLoader(args)
+    connector_options, _ = config_loader.get_umapi_options()
+    UmapiConnector.create_conn = False
+    umapi_connector = UmapiConnector('.primary', connector_options)
+    assert not umapi_connector.uses_business_id
+
+
+def test_uses_business_id_unspecified(tmp_config_files, modify_umapi_config, cli_args, private_key):
+    root_config, _, _ = tmp_config_files
+    modify_umapi_config(['enterprise', 'priv_key_path'], private_key)
+    args = cli_args({'config_filename': root_config})
+    config_loader = ConfigLoader(args)
+    connector_options, _ = config_loader.get_umapi_options()
+    UmapiConnector.create_conn = False
+    umapi_connector = UmapiConnector('.primary', connector_options)
+    assert not umapi_connector.uses_business_id

user_sync/connector/connector_umapi.py

@@ -44,7 +44,10 @@
 
 
 class UmapiConnector(object):
-    def __init__(self, name, caller_options):
+    # class-level flag that determines if we are creating a UMAPI connection
+    # set to False if using in a unit test
+    create_conn = True
+    def __init__(self, name, caller_options, is_primary=False):
         """
         :type name: str
         :type caller_options: dict
@@ -54,6 +57,8 @@ def __init__(self, name, caller_options):
         self.trusted = caller_config.get_bool('trusted', True)
         if self.trusted is None:
             self.trusted = False
+        self.uses_business_id = caller_config.get_bool('uses_business_id', True)
+        self.is_primary = is_primary
         builder = config_common.OptionsBuilder(caller_config)
         builder.set_string_value('logger_name', self.name)
         builder.set_bool_value('test_mode', False)
@@ -95,26 +100,27 @@ def __init__(self, name, caller_options):
         enterprise_config.report_unused_values(logger)
         # open the connection
         um_endpoint = "https://" + server_options['host'] + server_options['endpoint']
-        logger.debug('%s: creating connection for org %s at endpoint %s', self.name, org_id, um_endpoint)
-        try:
-            self.connection = connection = umapi_client.Connection(
-                org_id=org_id,
-                auth_dict=auth_dict,
-                ims_host=ims_host,
-                ims_endpoint_jwt=server_options['ims_endpoint_jwt'],
-                user_management_endpoint=um_endpoint,
-                test_mode=options['test_mode'],
-                user_agent="user-sync/" + app_version,
-                logger=self.logger,
-                timeout_seconds=float(server_options['timeout']),
-                retry_max_attempts=server_options['retries'] + 1,
-                ssl_verify=options['ssl_cert_verify']
-            )
-        except Exception as e:
-            raise AssertionException("Connection to org %s at endpoint %s failed: %s" % (org_id, um_endpoint, e))
-        logger.debug('%s: connection established', self.name)
-        # wrap the connection in an action manager
-        self.action_manager = ActionManager(connection, org_id, logger)
+        if self.create_conn:
+            logger.debug('%s: creating connection for org %s at endpoint %s', self.name, org_id, um_endpoint)
+            try:
+                self.connection = connection = umapi_client.Connection(
+                    org_id=org_id,
+                    auth_dict=auth_dict,
+                    ims_host=ims_host,
+                    ims_endpoint_jwt=server_options['ims_endpoint_jwt'],
+                    user_management_endpoint=um_endpoint,
+                    test_mode=options['test_mode'],
+                    user_agent="user-sync/" + app_version,
+                    logger=self.logger,
+                    timeout_seconds=float(server_options['timeout']),
+                    retry_max_attempts=server_options['retries'] + 1,
+                    ssl_verify=options['ssl_cert_verify']
+                )
+            except Exception as e:
+                raise AssertionException("Connection to org %s at endpoint %s failed: %s" % (org_id, um_endpoint, e))
+            logger.debug('%s: connection established', self.name)
+            # wrap the connection in an action manager
+            self.action_manager = ActionManager(connection, org_id, logger)
 
     def get_users(self):
         return list(self.iter_users())

user_sync/engine/umapi.py

@@ -27,6 +27,7 @@
 import user_sync.connector.connector_umapi
 import user_sync.error
 import user_sync.identity_type
+from user_sync.connector.connector_umapi import UmapiConnector
 from user_sync.helper import normalize_string, CSVAdapter, JobStats
 from user_sync.config.common import check_max_limit
 
@@ -112,6 +113,7 @@ def __init__(self, caller_options):
         self.primary_users_created = set()
         self.secondary_users_created = set()
         self.updated_user_keys = set()
+        self.primary_users_by_email: dict[str, dict] = {}
 
         # stray key input path comes in, stray_list_output_path goes out
         self.stray_key_map = {}
@@ -882,7 +884,7 @@ def update_umapi_user(self, umapi_info, user_key, attributes_to_update=None, gro
         commands.add_groups(groups_to_add)
         return commands
 
-    def update_umapi_users_for_connector(self, umapi_info, umapi_connector):
+    def update_umapi_users_for_connector(self, umapi_info, umapi_connector: UmapiConnector):
         """
         This is the main function that goes over adobe users and looks for and processes differences.
         It is called with a particular organization that it should manage groups against.
@@ -920,6 +922,9 @@ def update_umapi_users_for_connector(self, umapi_info, umapi_connector):
         # Walk all the adobe users, getting their group data, matching them with directory users,
         # and adjusting their attribute and group data accordingly.
         for umapi_user in umapi_users:
+            # if target is ESM, then treat existing AdobeID (i.e. businessID) as linked identity type
+            if umapi_connector.uses_business_id and umapi_user['email'] in self.primary_users_by_email:
+                umapi_user['type'] = self.primary_users_by_email[umapi_user['email']]['type']
             # let save adobeID users to a seperate list
             self.filter_adobeID_user(umapi_user)
             # get the basic data about this user; initialize change markers to "no change"
@@ -948,6 +953,9 @@ def update_umapi_users_for_connector(self, umapi_info, umapi_connector):
 
             self.map_email_override(umapi_user)
 
+            if umapi_connector.is_primary:
+                self.primary_users_by_email[umapi_user['email']] = umapi_user
+
             directory_user = filtered_directory_user_by_user_key.get(user_key)
             if directory_user is None:
                 # There's no selected directory user matching this adobe user