SharePoint SPFx & integration: Choosing the right user identifier for external system relationships

User attribute mapping for an external system relationship

When building SharePoint-integrated applications—such as a Shop system embedded via SPFx in SharePoint — we often face a subtle but critical challenge: how to reliably link a user to data stored in an external system. A typical example is assigning orders to the user who created them. At first glance, this seems straightforward—until user properties start changing. 😒

In SharePoint Framework (SPFx), the current user is available via this.context.pageContext.user. This object exposes several properties like displayName, email, id, and loginName. However, not all of these are suitable for use as a stable foreign key in an external database.

Properties such as displayName and email are mutable. If an administrator updates these values in Entra ID or SharePoint, the changes will eventually propagate—but not instantly. Synchronization delays and site-specific caching (via the User Information List) can lead to temporary inconsistencies. This makes them unreliable for persistent relationships.

The "id" property, while often used internally in SharePoint (e.g., in User Fields), is also problematic. It is scoped to a site collection, meaning the same user can have different IDs across different sites. Moreover, if a user is removed and re-added, the ID may change, breaking existing references.

The most robust option is the loginName. In SharePoint Online, this typically appears as a claims-based identifier like "i:0#.f|membership|user@tenant.onmicrosoft.com". This value is effectively immutable for a given account and remains consistent across site collections. Even if the user’s display name or email changes, the "loginName" remains stable.

There are edge cases to consider. For example, if a user is deleted and later recreated with the same UPN (a “rehired” scenario), SharePoint may retain the old user entry in the User Information List. This can lead to mismatches and access issues. Still, for most integration scenarios, "loginName" (or the UPN derived from it) is the best available choice for a durable, cross-system identifier.

My Conclusion

When designing integrations between SharePoint and external systems, choosing the right user identifier is essential. Avoid mutable or site-specific properties, and favor loginName as a stable, globally consistent reference. This ensures that user-to-data relationships remain intact—even as user profiles evolve over time.