Skip to content

Attribute Filtering

Troubleshooting Attribute Filtering

Attribute filtering in Entra ID Connect determines which on-premises directory attributes are synchronized to Azure AD. Misconfigurations here can lead to missing or incorrect data in Azure AD. This section outlines steps to diagnose and resolve common attribute filtering issues.

1. Verify Attribute Filtering Configuration

Ensure attributes are explicitly included in the sync rules and mapped correctly.

Steps:
- Open the Azure AD Connect tool and navigate to Attribute Filtering.
- Confirm that required attributes (e.g., userPrincipalName, mail) are enabled for synchronization.
- Check attribute mappings in the Attribute Mapping section to ensure they match between on-premises and Azure AD.

PowerShell Example:

# Check current attribute filtering rules  
Get-ADSyncAttributeFilter | Where-Object { $_.RuleType -eq "AttributeFiltering" }

If an attribute is missing, enable it via the GUI or use the Set-ADSyncAttributeFilter cmdlet to update rules.

2. Check for Attribute Conflicts

Conflicting attribute values (e.g., duplicate userPrincipalName) can prevent synchronization.

Steps:
- Use the Azure AD Connect Health portal to identify conflicts.
- Run the Directory Sync Health report to spot errors like Attribute value conflict.
- Manually verify attribute uniqueness in the on-premises directory using tools like ldapsearch or Active Directory Users and Computers.

Example Command:

# Check for duplicate userPrincipalNames in Active Directory  
ldapsearch -x -H ldap://dc.example.com -b "CN=Users,DC=example,DC=com" "(userPrincipalName=*)" userPrincipalName

3. Validate Attribute Data Quality

Invalid or inconsistent data (e.g., null values, special characters) can cause sync failures.

Steps:
- Audit the on-premises directory for invalid attribute values.
- Use PowerShell to filter and validate data:

# Check for null values in the mail attribute  
Get-ADUser -Filter * -Properties mail | Where-Object { $_.mail -eq $null }
- Correct invalid data in the source directory before re-syncing.

4. Review Sync Logs for Errors

Sync errors related to attribute filtering are logged in the Event Viewer or sync log files.

Steps:
- Open Event Viewer > Windows Logs > Directory Sync.
- Filter for event ID 1000 (sync errors) or 1001 (attribute conflicts).
- Examine the error message for details (e.g., "Attribute 'mail' is not allowed").

Example Log Entry:

Event ID 1000: Error syncing attribute 'mail' for user CN=John Doe,DC=example,DC=com. Reason: Attribute is not included in the attribute filtering rules.

5. Test with a Subset of Attributes

Isolate the issue by syncing a limited set of attributes.

Steps:
- Temporarily disable non-essential attributes in Attribute Filtering.
- Run a Delta Sync or Full Sync to test if the issue persists.
- Re-enable attributes incrementally to identify problematic ones.

PowerShell Example:

# Temporarily disable the 'department' attribute  
Set-ADSyncAttributeFilter -Identity "AttributeFilteringRule" -ExcludeAttributes department

6. Use Azure AD Connect Health Portal

The health portal provides real-time insights into sync issues.

Steps:
- Navigate to Azure AD Connect Health > Sync Health.
- Check the Sync Health Summary for warnings or errors related to attribute filtering.
- Use the Sync Diagnostic tool to generate a report.

Key takeaways

  • Always verify attribute inclusion and mappings in Attribute Filtering settings.
  • Use sync logs and health reports to identify specific attribute conflicts or errors.
  • Validate data quality in the on-premises directory before sync operations.
  • Test attribute filtering changes in a controlled environment to avoid disruptions.
  • Leverage tools like Azure AD Connect Health for proactive monitoring and diagnostics.