Attribute Sync Configuration

Control which identity attributes are collected during Active Directory and Entra ID synchronization.

Requires role: Operator (read), Admin (write) Related: Stale Identity Detection, Over-Permission Analytics

Overview

When GraphnAI synchronizes identities from Active Directory or Entra ID, it collects a wide range of attributes for each user, group, computer, and service principal. Some of these attributes are essential for security analysis (like group memberships and permissions), while others provide additional context (like job titles and office locations) or contain sensitive personal information (like phone numbers and addresses).

The Attribute Sync Configuration feature gives administrators control over which attributes are collected during synchronization. This allows you to:

• Minimize PII collection for GDPR, HIPAA, or other compliance requirements
• Reduce sync payload size by disabling unneeded optional attributes
• Enable advanced analytics by collecting recommended attributes like department and job title (needed for peer group analysis)
• Control license requirements by disabling attributes that require elevated Entra ID licenses

Attributes are organized into three categories:

• Required: Always collected, cannot be disabled. These are essential for core platform functionality.
• Recommended: Enabled by default but can be toggled off. These enhance analytics and provide useful context without requiring special permissions or licenses.
• Optional: Disabled by default but can be toggled on. These are typically PII fields or niche attributes that most customers don't need.

Changes to attribute configuration take effect on the next full or delta sync for the affected bridge or identity provider.

Prerequisites

• Role: Operator role to view current configuration, Admin role to modify it
• Data source: At least one configured bridge (for Active Directory) or OIDC provider (for Entra ID)

Accessing Attribute Configuration

For Active Directory (Bridge)

1. Log in to GraphnAI with an Admin account
2. Navigate to Bridges in the sidebar
3. Click on the bridge you want to configure
4. Scroll down to the Sync Attributes section

For Entra ID (Identity Provider)

1. Log in to GraphnAI with an Admin account
2. Navigate to Admin > Identity Providers in the sidebar
3. Click on the provider you want to configure
4. Scroll down to the Sync Attributes section

Understanding Attribute Categories

Required Attributes

Required attributes are locked and cannot be disabled. These are essential for GraphnAI to function correctly and include:

• Core identity fields: objectGUID, objectSid, sAMAccountName, displayName, userPrincipalName
• Graph topology: memberOf, primaryGroupID, groupTypes
• Security analysis: nTSecurityDescriptor (for ACL edge building), adminCount (for Tier 0 detection)
• Staleness detection: lastLogonTimestamp (AD), signInActivity (Entra), approximateLastSignInDateTime (Entra devices)
• Peer grouping: department, title/jobTitle (needed for over-permission analytics)
• Credential lifecycle: pwdLastSet (AD), lastPasswordChangeDateTime (Entra), keyCredentials, passwordCredentials

These fields are marked with a lock icon and cannot be toggled.

Recommended Attributes

Recommended attributes are enabled by default but can be disabled if not needed. These provide useful context for investigations and the Identity Details panel without requiring special permissions or licenses in most cases:

Active Directory examples:

• User description, email, manager, UPN, account expiration
• Group description, owner, creation date
• Computer description, owner

Entra ID examples:

• Employee type, company name, office location
• Group visibility, classification, dynamic membership rules
• Service principal tags, notes
• Device manufacturer, model, registration date

Most recommended attributes are safe to leave enabled. They don't contain highly sensitive PII and enhance the value of the platform.

Important exception: The Entra ID attribute signInActivity is marked as Recommended but has special license and permission requirements (see License and Permission Notes below).

Optional Attributes

Optional attributes are disabled by default and must be explicitly enabled. These typically fall into two categories:

1. PII fields (marked with an amber warning icon):

   • Personal names (givenName, surname)
   • Phone numbers (mobile, telephoneNumber, businessPhones)
   • Physical addresses (streetAddress, city, state, postalCode, country)
   • HR identifiers (employeeId, employeeHireDate)
   • Photos (thumbnailPhoto)

2. Niche technical fields:

   • Windows profile paths (homeDirectory, scriptPath, profilePath)
   • Intune device enrollment details (enrollmentType, mdmAppId)
   • Application permission manifests (requiredResourceAccess)

Enable optional attributes only if you have a specific use case for them. For example, if you're building automation that correlates identities with HR systems, you might enable employeeId.

Configuring Attributes

Viewing Current Configuration

1. Navigate to the Sync Attributes section for your bridge or identity provider
2. Expand the object type you want to inspect (User, Group, Computer, etc.) by clicking its header
3. The panel shows three sections for each type: Required, Recommended, and Optional
4. Each attribute displays:
   • Name: The LDAP attribute name (AD) or Microsoft Graph property name (Entra)
   • Description: What the attribute contains
   • Enabled state: Toggle switch (for Recommended/Optional) or lock icon (for Required)
   • Privacy notes: Amber warning icon for PII fields (hover to see details)
   • License notes: Blue info icon for attributes requiring special licenses (hover to see details)
   • Permission notes: Blue info icon for attributes requiring special permissions (hover to see details)

Enabling or Disabling Attributes

1. Expand the object type you want to configure
2. Locate the attribute in the Recommended or Optional section
3. Click the toggle switch next to the attribute name:
   • Toggle ON (blue): Attribute will be collected during sync
   • Toggle OFF (gray): Attribute will not be collected
4. Repeat for any other attributes you want to change
5. Click the Save button in the top-right corner of the Sync Attributes section
6. The configuration is saved immediately and will take effect on the next sync

Note: You can make multiple changes before clicking Save. The UI tracks pending changes and enables the Save button only when you have unsaved modifications.

Reloading Configuration

To discard unsaved changes and reload the current saved configuration:

1. Click the Reload button in the top-right corner of the Sync Attributes section
2. All pending changes are discarded and the UI refreshes with the saved configuration

License and Permission Notes

Entra ID signInActivity Attribute

The signInActivity attribute is classified as Recommended but has special requirements:

• License: Requires Entra ID Premium P1 or P2 license for your tenant
• Permission: Requires the AuditLog.Read.All Microsoft Graph API permission

If your tenant does not have a P1/P2 license or the permission is not granted, the GraphnAI server will automatically retry the user list call without signInActivity and log a warning. Staleness detection for Entra users will fall back to using the lastSeen timestamp instead of actual sign-in activity.

What this means:

• If you have P1/P2 and the permission, leave it enabled for accurate Entra staleness detection
• If you don't have P1/P2 or the permission, you can disable it to avoid the automatic fallback and warning messages

The platform handles the fallback gracefully, so you can leave it enabled even if you're unsure about your license status. The server will detect the 403 error and adjust automatically.

Active Directory Attributes

All Required and Recommended Active Directory attributes are readable by a standard Domain User account in default AD configurations. No elevated permissions or special licenses are required.

In hardened environments where DACL read access is restricted, the nTSecurityDescriptor attribute may fail to read for some objects. This is handled gracefully: ACL edges will not be built for those objects, but all other sync operations continue normally.

Example: Minimizing PII Collection for GDPR Compliance

Your organization is subject to GDPR and wants to minimize the collection of personal information in GraphnAI.

Steps:

1. Navigate to Bridges in the sidebar and select your Active Directory bridge
2. Expand the user object type in the Sync Attributes section
3. In the Recommended section, disable the following attributes if not needed:
   • mail (if you don't need email addresses for user correlation)
   • manager (if you don't use the org chart for investigations)
4. Verify that all Optional attributes remain disabled (they are off by default)
5. Click Save
6. Repeat for any Entra ID providers: Navigate to Admin > Identity Providers in the sidebar, select the provider, and configure attributes
7. For Entra, disable optional PII fields like:
   • streetAddress, city, state, postalCode, country
   • mobilePhone, businessPhones
   • employeeId, employeeHireDate

On the next sync, GraphnAI will no longer collect these PII fields. Existing data in the graph remains until you perform a manual cleanup or allow nodes to age out via tombstone deletion.

Example: Enabling Peer Group Analytics

Your security team wants to use the Over-Permission Analytics feature to detect users with excessive permissions compared to their peer group. This feature depends on department and title attributes.

Steps:

1. Verify that department and title are collected:
   • For Active Directory: Both are Required and always collected
   • For Entra ID: Both are Required (department and jobTitle map to the same peer grouping logic)
2. No configuration changes are needed — these attributes are automatically collected
3. Trigger a full sync for each bridge to populate the attributes for existing identities
4. Wait for the background processing to complete criticality evaluation
5. Navigate to Analysis > Over-Permission to see the peer group analysis

These attributes are Required and cannot be disabled. They are collected automatically during every sync.

Example: Collecting HR Employee IDs for Automation

Your team is building automation that correlates GraphnAI identities with an HR system using employee IDs.

Steps:

1. Navigate to Bridges in the sidebar or Admin > Identity Providers in the sidebar
2. Select the bridge or provider you want to configure
3. Expand the user object type
4. In the Optional section, locate employeeID (AD) or employeeId (Entra)
5. Toggle the attribute ON (switch turns blue)
6. Click Save
7. Trigger a full sync to backfill the attribute for all existing users
8. Access the attribute via the Identity Details panel: it will appear in the properties field of each user node

When Changes Take Effect

Attribute configuration changes take effect on the next sync for the affected bridge or identity provider. This applies to both full and delta syncs.

For Active Directory bridges:

• Changes are pushed to the bridge via WebSocket immediately after you save
• The bridge applies the new configuration on the next scheduled or manually triggered sync
• Delta syncs use the updated attribute list, so newly collected attributes appear immediately
• Attributes that were disabled will no longer be updated, but existing data remains in the graph until you manually clean it up

For Entra ID providers:

• Changes are stored in the GraphnAI server database
• The next sync (triggered manually or via schedule) builds a new $select query string using the updated configuration
• The Microsoft Graph API returns only the requested attributes
• Disabled attributes will no longer be updated in the graph

Backfilling attributes: If you enable a new attribute (e.g., switching employeeID from disabled to enabled), you must trigger a full sync to backfill the attribute for all existing identities. Delta syncs only update identities that have changed since the last sync, so newly enabled attributes won't be populated for unchanged identities until a full sync occurs.

Troubleshooting

I enabled an attribute but it's not appearing in the Identity Details panel

Possible causes:

• No sync has run yet: Attribute changes take effect on the next sync. Trigger a manual sync.
• Delta sync only: If you enabled a new attribute, you need a full sync to backfill it for existing identities.
• Attribute is empty in source: The attribute may be enabled but not populated in Active Directory or Entra ID for that identity.

Solution:

1. Navigate to the Bridge detail page Sync History section (or the equivalent for IdPs)
2. Check that a sync has completed after you saved the configuration change
3. If only delta syncs have run, trigger a full sync to backfill the attribute
4. Verify the attribute exists in the source directory by checking the object directly in AD or Entra

Entra sync fails with "Insufficient privileges" after enabling signInActivity

Cause: Your Entra ID app registration does not have the AuditLog.Read.All permission, or the permission has not been granted admin consent.

Solution:

1. Navigate to the Azure Portal > App Registrations > [Your GraphnAI App]
2. Go to API Permissions
3. Add AuditLog.Read.All (Application permission, not Delegated)
4. Click Grant admin consent
5. Wait 5-10 minutes for permission propagation
6. Retry the sync

Alternatively, disable the signInActivity attribute in the GraphnAI attribute configuration to avoid the error. The platform will fall back to using lastSeen for Entra staleness detection.

I disabled a PII attribute but it still appears in the graph

Cause: Disabling an attribute prevents it from being updated on future syncs, but it does not delete existing data from the graph.

Solution:

To remove existing PII data, you have two options:

1. Manual cleanup (if you have direct database access):

   • Use a database query to unset the property from all affected identity documents

2. Wait for natural data refresh:

   • If the attribute is disabled, it will not be updated on future syncs
   • Over time, as identities are re-synced or deleted, the old data will age out
   • This is slower but requires no manual intervention

Attribute configuration returns 403 Forbidden

Cause: Your user account does not have the Admin role.

Solution: Attribute configuration requires Admin privileges. Contact an existing Admin to:

• Grant you Admin role via Admin > User Management in the sidebar, or
• Make the attribute changes on your behalf

Best Practices

1. Start with defaults: The default Required + Recommended configuration is designed for most customers. Only customize if you have specific compliance or performance requirements.

2. Enable attributes before analytics: If you plan to use Over-Permission Analytics or Stale Identity Detection, ensure that department, title/jobTitle, lastLogonTimestamp, and signInActivity are enabled (they are Required by default).

3. Minimize PII where possible: If you don't need personal phone numbers, addresses, or photos for security analysis, leave them disabled to reduce compliance risk.

4. Document your overrides: If you disable a recommended attribute or enable an optional one, document the reason in your internal runbook so future administrators understand the rationale.

5. Test before production: If you're unsure whether disabling a recommended attribute will break a workflow, test the change in a non-production environment first.

6. Backfill with full syncs: After enabling a new attribute, always trigger a full sync to ensure all existing identities are updated with the new data.

7. Monitor sync logs: After changing attribute configuration, check the sync logs for errors related to missing or malformed attributes. The bridge and server log warnings if an expected attribute is not found in the source.

Security Considerations

• PII exposure: Collecting optional PII attributes increases your compliance burden. Only enable them if you have a documented business need.
• License requirements: Enabling signInActivity may require Entra ID P1/P2 licenses. Verify your licensing before enabling it.
• Attribute integrity: Disabling a Required attribute (which you cannot do via the UI) would break core platform functionality. This is why Required attributes are locked.
• Data retention: Disabling an attribute does not delete existing data. Plan for manual cleanup if you need to remove PII for compliance reasons.

Related Documentation

• Stale Identity Detection — Depends on lastLogonTimestamp and signInActivity attributes
• Over-Permission Analytics — Depends on department and title/jobTitle attributes