Entra External ID: Federated email claim not present in OnAttributeCollectionStart/Submit payload

Hello Yuliia Bashko

Thank you for reaching out to Microsoft Q&A.

It looks like you’ve hit a gap in how Entra External ID surfaces the built-in email attribute in custom auth extension events when you’re doing a federated OIDC sign-up. Here’s the short of it:

• What’s happening

– Your IdP is correctly returning an email claim and you’ve mapped it in your user flow.

– The sign-up UI shows it, but the same email field is deliberately omitted from the payloads for the OnAttributeCollectionStart and OnAttributeCollectionSubmit events.

– You proved it only by mapping it to something else (postalCode), at which point it shows up.

• Why

– At this time, the “email” built-in user attribute in External ID flows is only fully wired through for local (username/password) sign-ups and for token issuance events. It’s not surfaced to the attribute-collection extension hooks for federated flows.

– Basically, email is treated as a “reserved” attribute and isn’t passed along in those two extension event payloads.

• Workarounds

1. Map the incoming email claim to a custom or extension attribute (e.g. userDefinedEmail), include it in your user flow, and then read that in your extension.
2. Move your logic to the Pre-Token-Generation extension point (the microsoft.graph.authenticationEvent.tokenIssuanceStart event). In that event payload you’ll see all incoming claims (including federated email) in event.data.requestContext.claims.
3. As a last resort, after sign-up you could call Microsoft Graph from your extension (with the proper Graph-API permissions) to pull the user’s mail property, but that adds latency and complexity.

Reference docs

1. Custom authentication extensions overview https://learn.microsoft.com/azure/api-management/api-management-howto-entra-external-id
2. Built-in and custom user attributes in External ID https://learn.microsoft.com/azure/active-directory/external-identities/customers/how-to-define-custom-attributes
3. Adding business logic with custom extensions https://learn.microsoft.com/azure/active-directory/external-identities/customers/concept-custom-extensions

Let us know the above steps helps

Thanks

Hi @Shubham Sharma

The option with custom or extension attribute (e.g. userDefinedEmail) seams great idea.
The problem is I do not understand how I can map email claim to userDefinedEmail, as for me, extension attribute is more about adding additional information about the user using custom extension events. Mapping federated claims is configured on the OIDC provider configuration, and I do not see how to add a custom extension attribute there.
Can you help me here?

Yuliia Bashko

Thank you for your reply.

I am checking with the internal team and get back to you shortly.

@Shubham Sharma

Do you have any updates?

Yuliia Bashko

Thank you for your reply.

Claim mapping (IdP → attributes) and custom authentication extensions are two different plumbing layers, and extension attributes are not populated by extensions — they can be populated before extensions run if wired correctly.

Below is the resolution

What actually works: -

You can map a federated IdP email claim into a custom user attribute (for example userDefinedEmail) without using extensions at all.

You do this by:

1. Creating a custom user attribute
2. Selecting that attribute in the User Flow
3. Mapping the IdP claim → that custom attribute in the IdP configuration
4. Reading it in OnAttributeCollectionStart / Submit

This is explicitly supported and is how Microsoft expects you to pass federated values into extension payloads.

Why it is confusing

You’re absolutely right that:

• Extensions feel like the place where “custom attributes” belong
• IdP claim mapping UI doesn’t visually distinguish built‑in vs custom attributes well

But in External ID:

• Extensions do not “create” attributes
• User flows own the attribute schema
• IdP claim mapping can target both built‑in and custom attributes You’re absolutely right that:
  • Extensions feel like the place where “custom attributes” belong
  • IdP claim mapping UI doesn’t visually distinguish built‑in vs custom attributes well

Below is the solution:-

1. Create a custom user attribute

In Microsoft Entra admin center:

External Identities

→ Custom user attributes

→ Add

Example:

Name: userDefinedEmail

Data type: String

https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/azure-entra-external-id-setup?tabs=powershell-script

2 Add the attribute to your user flow

External Identities

→ User flows

→ Your sign-up/sign-in flow

→ User attributes

Select:

userDefinedEmail

This makes the attribute:

Available to the flow

Writable during sign-up

Available to extensions

3 Map the federated email claim → custom attribute

This is the step you were missing

External Identities

→ Identity providers

→ Your OIDC provider

→ Attribute mapping

Add or update mapping:

the IdP mapping UI allows mapping to any user-flow-enabled attribute, including custom ones.

https://learn.microsoft.com/en-us/entra/external-id/claims-mapping

Read it inside the extension payload

Now your extension will receive it:

"userSignUpInfo": {

  "attributes": {

    "displayName": "Test User",

    "givenName": "Test",

    "surname": "User",

    "userDefinedEmail": "user@example.com"

  }

}

This works because:

• Custom attributes are not reserved
• Attribute-collection extensions are designed to surface them

https://learn.microsoft.com/en-us/azure/healthcare-apis/fhir/azure-entra-external-id-setup?tabs=powershell-script

Why email behaves differently

Microsoft currently treats email as a protected, system attribute:

Shown in UI - True

Used for account linking -True

Available in token issuance -True

Not exposed to attribute-collection extensions for federated flows -False

This limitation does not apply to:

Custom user attributes

Extension attributes

Token issuance events (tokenIssuanceStart)

What you observed (email appearing when mapped to postalCode) is the expected side effect of this rule.