Contact linking with Azure AD B2C

Contact linking refers to the process of associating one or more identities (email addresses, social accounts, enterprise logins, etc.) with a single user or contact record in a customer relationship management (CRM) system or user database. This allows users to sign in with different providers but still be treated as one user within your system.

In Azure Active Directory B2C (Azure AD B2C), contact linking is not a built-in feature like in CRM platforms, but you can customize user flows or use custom policies (Identity Experience Framework) to implement it.

---

Step 1: Understand the Use Case

Examples of when contact linking is useful:

• A user registers with Facebook but later signs in using Google
• A user signs in with a local email/password, then links their Microsoft account
• An enterprise user signs in with Azure AD and links a personal account

In all cases, you want these to map to one user/contact record in your backend system.

---

Step 2: Set Up Azure AD B2C Tenant

If not done already:

1. Create your Azure AD B2C tenant via Azure Portal
2. Link the tenant to your Azure subscription
3. Register applications (web/mobile/API) in B2C
4. Add identity providers (local, social, or enterprise) under Identity Providers

---

Step 3: Enable Multiple Identity Providers

Go to Azure AD B2C > Identity Providers and configure:

• Facebook
• Google
• Microsoft
• Local accounts (email/password)
• Enterprise logins (SAML, Azure AD)

These will be used by users to sign in with various identities.

---

Step 4: Use Custom Policies (IEF) – Required for Linking

Azure AD B2C built-in user flows do not support account linking natively. To implement contact linking:

• Use Identity Experience Framework (IEF) or custom policies
• This gives you control over claims, technical profiles, and conditional orchestration

Prerequisites:

• Download the starter pack from Microsoft’s GitHub repo
• Set up base, extensions, and relying party (RP) policies
• Upload them to your B2C tenant

---

Step 5: Create or Extend Your Custom Policy for Contact Linking

Modify your custom policy to:

1. Capture multiple identities
2. Match them to the same contact record
3. Link external logins to the same internal account

You can achieve this by:

• Querying a backend REST API after login to check if this identity already exists
• Using custom claims like email, objectId, alternativeId
• Allowing a decision point: if not linked, prompt the user to link or register

---

Step 6: Design the Linking Experience

There are several options:

• Automatic linking: If email from Facebook and Google match, link accounts automatically
• Manual linking: Ask the user to confirm identity if login from new provider
• After login: Offer a profile management screen with “Link Account” options

Use OrchestrationSteps in the custom policy to:

• Redirect to custom HTML/CSS UI
• Call REST API to check linking
• Return decision back to B2C

---

Step 7: Implement the Backend Contact Matching API

This API will:

• Receive identity claims (email, provider, subject)
• Look up your CRM or user store for existing contact
• Return the contactId or instruct B2C to create a new contact

Example response:

{
  "action": "link",
  "contactId": "12345"
}

Ensure:

• It is secure (token-based or IP-whitelisted)
• Has logging and monitoring
• Can handle race conditions (e.g., two logins at the same time)

---

Step 8: Update B2C Claims and Persist the Linked Identity

Once linked:

• Save the linked provider details in user attributes or custom claims
• Use Azure AD B2C’s extension attributes (e.g., extension_LinkedProviders)
• Add claims like:
  • email
  • identities
  • contactId
  • lastLoginProvider

---

Step 9: Use Contact ID in Your App and APIs

In your backend (e.g., .NET, Node.js, Python), use the contactId or primary objectId from the token to:

• Load user profile
• Aggregate data from multiple identities
• Ensure all sessions point to the same logical user

---

Step 10: Test and Validate the Linking Flow

Test the scenarios:

• Register with Facebook, then login with Google
• Register with email, then try with Microsoft
• Try duplicate emails from different providers

Ensure:

• Tokens carry correct identity claims
• Contact matching logic is consistent
• User cannot access someone else’s data

---

Step 11: Offer Account Management Options

Let users:

• View linked accounts in profile settings
• Add new identity providers
• Remove linked accounts (with caution)
• Enforce re-authentication before account changes

---

Step 12: Audit and Secure the Linking Process

Log all linking and unlinking events:

• Who linked what identity and when
• Any suspicious attempts (e.g., linking to unrelated email)

Apply rate-limiting and risk-based conditional access where needed.

---

Step 13: Maintain and Scale

As your user base grows:

• Scale your contact linking API
• Monitor identity conflicts and duplicates
• Periodically review orphan identities

If you use CRM integration (e.g., Dynamics 365), sync contact IDs accordingly.