Overview
PhishingBox target information can be maintained by more than one integration method. For example, an organization may synchronize users and group membership from Microsoft Entra ID while maintaining a target's preferred language from a separate HR, reporting, or business system.
When multiple systems update the same targets, each target field should have a clearly defined source of truth. This article covers best practices for combining directory synchronization with API-managed fields without allowing one process to overwrite information maintained by another.
For information about configuring Microsoft synchronization, see Integrating an Account with Microsoft Entra ID (Azure AD) .
Click from the following to jump to the desired section:
- Assign a Source of Truth for Each Field
- Prevent Directory Sync From Replacing API-Managed Values
- Language Synchronization Example
- Synchronization Order
- Reconcile the Data Periodically
Assign a Source of Truth for Each Field
Before using multiple synchronization methods, determine which system is responsible for each target field.
A typical configuration may look like the following:
| Target Information | Recommended Source |
|---|---|
| Email address | Microsoft Entra ID |
| First and last name | Microsoft Entra ID |
| Department and title | Microsoft Entra ID |
| Group membership | Microsoft Entra ID |
| Active/inactive status | Microsoft Entra ID |
| Preferred language | External language source through the API |
The exact ownership model may be different for each organization. The important requirement is that two automated systems should not continually write conflicting values to the same field.
Prevent Directory Sync From Replacing API-Managed Values
The Microsoft integration in the integration store has advanced settings which allow for certain fields to be skipped when syncing targets into the platform.
If an external API process will maintain the target's language, configure the Microsoft integration so that synchronization does not update the Language target field.
The resulting workflow is:
- Microsoft synchronization creates and maintains targets and their directory information.
- Language is excluded from the fields Microsoft synchronization is permitted to replace.
- The external integration identifies the target and updates the language through
PATCH /api/v2/target/update. - Future Microsoft synchronization runs continue updating directory-owned fields without overwriting language.
This approach prevents a synchronization race in which an API update sets the correct language and a later directory synchronization replaces it with an empty, outdated, or different value.
Language Synchronization Example
Assume the organization has the following user:
Email: jdoe@example.com Entra ID language: blank HR preferred language: fr_CA
Microsoft Entra ID can continue synchronizing the user's normal account information while the Language field is configured to be skipped.
The language synchronization process can then issue an API update similar to:
{
"id": "<target_uuid>",
"fields": {
"email": "jdoe@example.com",
"language": "fr_CA"
}
}On later directory synchronization runs, the fr_CA value remains under control of the language integration because the directory sync has been configured not to update that field.
Alternative: Use Microsoft as the Language Source
If the organization can reliably populate preferredLanguage in Microsoft Entra ID, a separate API process may not be necessary.
The Microsoft integration supports mapping the Entra ID preferredLanguage attribute to the PhishingBox language field.
The integration also provides an option to retrieve a user's language from mailbox settings when the language is otherwise unavailable. Organizations should evaluate whether one of these approaches can make Microsoft the authoritative source before creating a custom synchronization process.
Synchronization Order
Where possible, avoid designing integrations that depend on two jobs always executing in a specific order.
For example, the following design is fragile:
1. Microsoft sync updates all fields 2. Language job runs immediately afterward and corrects language
If the second job is delayed or fails, an incorrect language value may remain until the next successful run.
A more reliable configuration assigns field ownership so that Microsoft never attempts to update the externally managed language field in the first place.
Reconcile the Data Periodically
Even event-driven integrations should include periodic reconciliation.
A reconciliation process can compare the authoritative language source against the current PhishingBox target information and identify:
- Missing language values
- Unexpected language changes
- Targets that were added after the previous synchronization
- Users whose email address or identifier changed
- API updates that previously failed
Event-based updates provide speed, while periodic reconciliation provides confidence that the systems have not drifted apart.