Merge pull request #414 from adorton-adobe/feature/email-username

Support email-type federated users with different email addresses

Author: adorton-adobe

docs/en/user-manual/advanced_configuration.md

@@ -450,6 +450,37 @@ For domains that use username-based login, the `user_username_format` configurat
 
 If you are using username-based login, you must still provide a unique email address for every user, and that email address must be in a domain that the organization has claimed and owns. User Sync will not add a user to the Adobe organization without an email address.
 
+## Syncing Email-based Users with Different Email Address
+
+Some organizations must authenticate users with an internal-facing
+email-type ID such as user principal name, but wish to allow users to
+user their public-facing email address to log into Adobe products and
+use collaboration features.
+
+Internally, the Adobe Admin Console maintains a distinction between a
+user's email-type username and their email address.  These fields are
+normally set to the same value, but the Admin Console allows the
+email address to differ from the username.  The User Management API
+also supports the creation, update, and deletion of users that have
+different usernames and email addresses.
+
+**Note:** Any domain used in the email address field **must** be
+claimed and added to an Adobe identity directory.
+
+To use this functionality in the Sync Tool, simply specify both the
+`user_email_format` and the `user_username_format` options in
+`connector-ldap.yml`.
+
+```yaml
+user_email_format: "{mail}"
+user_username_format: "{userPrincipalName}"
+```
+
+In this scenario, the `user_username_format` option must map to a field
+that will always contain an email-type identifier (it does not need
+to be a live, working email address).  Users with non-email values
+will fail to be validated and synced.
+
 ## Protecting Specific Accounts from User Sync Deletion
 
 If you drive account creation and removal through User Sync, and want to manually create a few accounts, you may need this feature to keep User Sync from deleting the manually created accounts.

user_sync/rules.py

@@ -150,6 +150,10 @@ def __init__(self, caller_options):
             'hook_storage': None,
         }
 
+        # map of username to email address for users that have an email-type username that
+        # differs from the user's email address
+        self.email_override = {}  # type: dict[str, str]
+
         if logger.isEnabledFor(logging.DEBUG):
             options_to_report = options.copy()
             username_filter_regex = options_to_report['username_filter_regex']
@@ -612,6 +616,8 @@ def manage_strays(self, umapi_connectors):
         def get_commands(key):
             """Given a user key, returns the umapi commands targeting that user"""
             id_type, username, domain = self.parse_user_key(key)
+            if '@' in username and username in self.email_override:
+                username = self.email_override[username]
             return user_sync.connector.umapi.Commands(identity_type=id_type, username=username, domain=domain)
 
         # do the secondary umapis first, in case we are deleting user accounts from the primary umapi at the end
@@ -698,6 +704,13 @@ def create_umapi_commands_for_directory_user(self, directory_user, do_update=Fal
         :return user_sync.connector.umapi.Commands (or None if there's an error)
         """
         identity_type = self.get_identity_type_from_directory_user(directory_user)
+        update_username = None
+        if (identity_type == user_sync.identity_type.FEDERATED_IDENTITY_TYPE and directory_user['username'] and
+                '@' in directory_user['username'] and
+                normalize_string(directory_user['email']) != normalize_string(directory_user['username'])):
+            update_username = directory_user['username']
+            directory_user['username'] = directory_user['email']
+
         commands = user_sync.connector.umapi.Commands(identity_type, directory_user['email'],
                                                       directory_user['username'], directory_user['domain'])
         attributes = self.get_user_attributes(directory_user)
@@ -722,6 +735,8 @@ def create_umapi_commands_for_directory_user(self, directory_user, do_update=Fal
         else:
             attributes['option'] = 'ignoreIfAlreadyExists'
         commands.add_user(attributes)
+        if update_username is not None:
+            commands.update_user({"email": directory_user['email'], "username": update_username})
         return commands
 
     def create_umapi_user(self, user_key, groups_to_add, umapi_info, umapi_connector):
@@ -784,6 +799,16 @@ def update_umapi_user(self, umapi_info, user_key, umapi_connector,
             directory_user = umapi_user
             identity_type = umapi_user.get('type')
 
+        # if user has email-type username and it is different from email address, then we need to
+        # override the username with email address
+        if '@' in directory_user['username'] and directory_user['email'] != directory_user['username']:
+            if groups_to_add or groups_to_remove or attributes_to_update:
+                directory_user['username'] = directory_user['email']
+            if attributes_to_update and 'email' in attributes_to_update:
+                directory_user['email'] = umapi_user['email']
+                attributes_to_update['username'] = umapi_user['username']
+                directory_user['username'] = umapi_user['email']
+
         commands = user_sync.connector.umapi.Commands(identity_type, directory_user['email'],
                                                       directory_user['username'], directory_user['domain'])
         commands.update_user(attributes_to_update)
@@ -844,6 +869,8 @@ def update_umapi_users_for_connector(self, umapi_info, umapi_connector):
             if self.is_umapi_user_excluded(in_primary_org, user_key, current_groups):
                 continue
 
+            self.map_email_override(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
@@ -876,6 +903,18 @@ def update_umapi_users_for_connector(self, umapi_info, umapi_connector):
         umapi_info.set_umapi_users_loaded()
         return user_to_group_map
 
+    def map_email_override(self, umapi_user):
+        """
+        for users with email-type usernames that don't match the email address, we need to add some
+        special cases to update and disentitle users
+        :param umapi_user: dict
+        :return:
+        """
+        email = umapi_user.get('email', '')
+        username = umapi_user.get('username', '')
+        if '@' in username and username != email:
+            self.email_override[username] = email
+
     def is_umapi_user_excluded(self, in_primary_org, user_key, current_groups):
         if in_primary_org:
             self.primary_user_count += 1