Merge pull request #94652 from ArvindHarinder1/patch-31

Describe matching attributes

Author: PRMerger18

articles/active-directory/manage-apps/customize-application-attributes.md

@@ -73,6 +73,16 @@ Along with this property, attribute-mappings also support the following attribut
   - **Always** – Apply this mapping on both user creation and update actions.
   - **Only during creation** - Apply this mapping only on user creation actions.
 
+## Matching users in the source and target  systems
+The Azure AD provisioning service can be deployed in both greenfield (users do not exit in the target system) and brownfield (users already exist in the target system) scenarios. To support both scenarios, the provisioning service uses the concept of matching attribute(s). Matching attribute(s) allow you to determine how to uniquely identify a user in the source and match the user in the target. As part of planning your deployment, identify the attribute that can be used to uniquely identify a user in the source and target systems. Things to note:
+
+- **Matching attributes should be unique:** Customers often use attributes such as userPrincipalName, mail, or object ID as the matching attribute.
+- **Multiple attributes can be used as matching attributes:** You can define multiple attributes to be evaluated when matching users and the order in which they are evaluated (defined as matching precedence in the UI). If, for example, you define three attributes as matching attributes, and a user is uniquely matched after evaluating the first two attributes, the service will not evaluat the third attribute. The service will evaluate matching attributes in the order specified and stop evaluating when a match is found.  
+- **The value in the source and the target do not have to match exactly:** The value in the target can be some simple function of the value in the source. So, one could have an emailAddress attribute in the source and the userPrincipalName in the target, and match by a function of the emailAddress attribute that replaces some characters with some constant value.  
+- **Matching based on a combination of attributes is not supported:** Most applications do not support querying based on two properties and therfore it is not possible to match based on a combination of attributes. It is possible to evaluate single properties on after another.
+- **All users must have a value for at least one matching attribute:** If you define one matching attribute, all users must have a value for that attribute in the source system. If, for example, you define userPrincipalName as the matching attribute, all users must have a userPrincipalName. If you define multiple matching attribute (e.g. extensionAttribute1 and mail), not all users have to have the same matching attribute. One user could have a extensionAttribute1 but not mail while another user could have mail but no extensionAttribute1. 
+- **The target application must support filtering on the matching attribute:** Application developers allow filtering for a subset of attributes on their user or group API. For applications in the gallery, we ensure that the default attribute mapping is for an attribute that the target application's API does support filtering on. When changing the default matching attribute for the target application, check the third party API documentation to ensure that the attribute can be filtered on.  
+
 ## Editing group attribute-mappings
 
 A selected number of applications, such as ServiceNow, Box, and G Suite, support the ability to provision Group objects and User objects. Group objects can contain group properties such as display names and email aliases, along with group members.