From 4bc1ae7645c924d0250f963518b918c60d2c5336 Mon Sep 17 00:00:00 2001 From: Nandita Guilanians Date: Sun, 24 May 2026 16:08:51 -0700 Subject: [PATCH 1/3] docs: Add email optional for external IdP sign-up (preview) Add new section to OIDC federation article documenting how to make email not required for sign-up with external identity providers. Update claims mapping reference to reflect email can be optional. Related: AB#3293175 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- ...how-to-custom-oidc-federation-customers.md | 65 ++++++++++++++++++- ...reference-oidc-claims-mapping-customers.md | 4 +- 2 files changed, 66 insertions(+), 3 deletions(-) diff --git a/docs/external-id/customers/how-to-custom-oidc-federation-customers.md b/docs/external-id/customers/how-to-custom-oidc-federation-customers.md index a36a6ce3871..39adb5aa5fd 100644 --- a/docs/external-id/customers/how-to-custom-oidc-federation-customers.md +++ b/docs/external-id/customers/how-to-custom-oidc-federation-customers.md @@ -53,7 +53,7 @@ To configure OpenID Connect federation with your identity provider in Microsoft - Name - Given name - Family name - - Email (required) + - Email (required by default; can be [made optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview)) - Email_verified - Phone number - Phone_number_verified @@ -110,6 +110,67 @@ At this point, you set up the OIDC identity provider in your Microsoft Entra ID, 1. Select **Save**. +## Make email optional for external IdP sign-up (preview) + +By default, an email address is required when users sign up with an external identity provider. If your external IdP doesn't emit an email claim, users encounter the error `AADSTS901011: No email address was obtained from the external oidc identity provider` during sign-up. To avoid this error, you can configure your user flow to make the email attribute optional. This allows users to complete sign-up using only their external IdP identity, without providing an email address. + +> [!IMPORTANT] +> Making email not required is a user flow–level setting. This change applies to sign-ups for **all applications** associated with the user flow. + +> [!NOTE] +> When email is not collected, Email OTP can't be used for MFA. Ensure an alternative MFA method (such as SMS) is enabled if your policies require MFA. + +### Update the user flow to make email optional + +To make the email attribute optional in your user flow, use the Microsoft Graph API to update the `onAttributeCollection` property of the user flow. + +1. Find the ID of the user flow you want to update. One way to do this is to use [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) to list all your user flows: + + ```http + GET https://graph.microsoft.com/v1.0/identity/authenticationEventsFlows + ``` + + Locate the `id` of the user flow and the `onAttributeCollection` property in the response. + +1. Copy the `onAttributeCollection` property from the response, and use it to update the user flow with a `PATCH` request. The only change you need to make is to set the `required` property on the email attribute to `false`: + + ```http + PATCH https://graph.microsoft.com/v1.0/identity/authenticationEventsFlows/{user-flow-id} + Content-Type: application/json + + { + "@odata.type": "#microsoft.graph.externalUsersSelfServiceSignUpEventsFlow", + "onAttributeCollection": { + "@odata.type": "#microsoft.graph.onAttributeCollectionExternalUsersSelfServiceSignUp", + "attributeCollectionPage": { + "views": [ + { + "title": null, + "description": null, + "inputs": [ + { + "attribute": "email", + "label": "Email Address", + "inputType": "text", + "defaultValue": null, + "hidden": false, + "editable": true, + "writeToDirectory": true, + "required": false, + "validationRegEx": "^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*$", + "options": [] + } + ] + } + ] + } + } + } + ``` + + > [!NOTE] + > Include all the attribute inputs from your existing user flow in the `PATCH` request, not just the email attribute. The example above shows only the email input, but your user flow may include additional attributes. + ## Known limitations Conditional Access policies that require MFA registration don't function as expected when an External ID tenant is federated with an external identity provider (IdP). This can result in one of the following behaviors: @@ -117,6 +178,8 @@ Conditional Access policies that require MFA registration don't function as expe - Users are unable to register an MFA method and can't complete sign-in, often encountering an error. - Users aren't redirected to the MFA registration (sign-up) flow during sign-in as expected. +Additionally, a user created without an email address can't register an email address for use with Email OTP as an MFA method. + ## Related content - [Add a Microsoft Entra ID tenant as an OIDC identity provider](how-to-entra-id-federation-customers.md) diff --git a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md index a6b2820d9ea..5c1144c49f6 100644 --- a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md +++ b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md @@ -29,8 +29,8 @@ Use the following table to map standard OpenID Connect claims to corresponding u |name|Display Name|Full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user's locale and preferences.| |given_name|First Name|Given name(s) or first name(s) of the end-user.| |family_name|Last Name|Surname(s) or family name of the end-user.| -|email (required)|Email|Preferred e-mail address.| -|email_verified|N/A|In the received ID token, the value of this claim is true if the end-user's e-mail address has been verified by the identity provider; otherwise, false. When this claim value is true, this means that your identity provider took affirmative steps to ensure that this e-mail address was controlled by the end-user at the time the verification was performed. If this claim value is false or not mapped to any claim from the identity provider, the user will not be able to create an account. A verified email address is required for account creation. If the email is missing or unverified, an error message appears.| +|email (required by default)|Email|Preferred e-mail address. Email is required by default, but you can [make it optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview) for external IdP sign-up scenarios.| +|email_verified|N/A|Indicates whether the identity provider has verified the end-user's e-mail address. `true` means the identity provider took affirmative steps to ensure the e-mail address was controlled by the end-user. When email is required (the default), a verified email is needed for account creation — if `email_verified` is false, missing, or not mapped, account creation fails. If you've [configured email as optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview), this claim is not required for account creation.| |phone_number|Phone number|The claim provides the phone number for the user.| |phone_number_verified|N/A|In the received ID token, the value of this claim is true if the end-user's phone number has been verified; otherwise, false. When this claim value is true, this means that your identity provider took affirmative steps to verify the phone number.| |street_address|Street Address|Full mailing address, formatted for display or use on a mailing label. In the token response, this field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").| From 2b87cc44af3f8b115753840337001e221f4cf98e Mon Sep 17 00:00:00 2001 From: Nandita Guilanians Date: Sun, 24 May 2026 20:00:54 -0700 Subject: [PATCH 2/3] docs: Remove preview tags from email optional feature Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../customers/how-to-custom-oidc-federation-customers.md | 4 ++-- .../customers/reference-oidc-claims-mapping-customers.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/external-id/customers/how-to-custom-oidc-federation-customers.md b/docs/external-id/customers/how-to-custom-oidc-federation-customers.md index 39adb5aa5fd..da5823ac9ae 100644 --- a/docs/external-id/customers/how-to-custom-oidc-federation-customers.md +++ b/docs/external-id/customers/how-to-custom-oidc-federation-customers.md @@ -53,7 +53,7 @@ To configure OpenID Connect federation with your identity provider in Microsoft - Name - Given name - Family name - - Email (required by default; can be [made optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview)) + - Email (required by default; can be [made optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up)) - Email_verified - Phone number - Phone_number_verified @@ -110,7 +110,7 @@ At this point, you set up the OIDC identity provider in your Microsoft Entra ID, 1. Select **Save**. -## Make email optional for external IdP sign-up (preview) +## Make email optional for external IdP sign-up By default, an email address is required when users sign up with an external identity provider. If your external IdP doesn't emit an email claim, users encounter the error `AADSTS901011: No email address was obtained from the external oidc identity provider` during sign-up. To avoid this error, you can configure your user flow to make the email attribute optional. This allows users to complete sign-up using only their external IdP identity, without providing an email address. diff --git a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md index 5c1144c49f6..e9677f2045f 100644 --- a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md +++ b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md @@ -29,8 +29,8 @@ Use the following table to map standard OpenID Connect claims to corresponding u |name|Display Name|Full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user's locale and preferences.| |given_name|First Name|Given name(s) or first name(s) of the end-user.| |family_name|Last Name|Surname(s) or family name of the end-user.| -|email (required by default)|Email|Preferred e-mail address. Email is required by default, but you can [make it optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview) for external IdP sign-up scenarios.| -|email_verified|N/A|Indicates whether the identity provider has verified the end-user's e-mail address. `true` means the identity provider took affirmative steps to ensure the e-mail address was controlled by the end-user. When email is required (the default), a verified email is needed for account creation — if `email_verified` is false, missing, or not mapped, account creation fails. If you've [configured email as optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up-preview), this claim is not required for account creation.| +|email (required by default)|Email|Preferred e-mail address. Email is required by default, but you can [make it optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up) for external IdP sign-up scenarios.| +|email_verified|N/A|Indicates whether the identity provider has verified the end-user's e-mail address. `true` means the identity provider took affirmative steps to ensure the e-mail address was controlled by the end-user at the time the verification was performed. When email is required (the default), a verified email is needed for account creation — if `email_verified` is false, missing, or not mapped, account creation fails. If you've [configured email as optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up), this claim is not required for account creation.| |phone_number|Phone number|The claim provides the phone number for the user.| |phone_number_verified|N/A|In the received ID token, the value of this claim is true if the end-user's phone number has been verified; otherwise, false. When this claim value is true, this means that your identity provider took affirmative steps to verify the phone number.| |street_address|Street Address|Full mailing address, formatted for display or use on a mailing label. In the token response, this field MAY contain multiple lines, separated by newlines. Newlines can be represented either as a carriage return/line feed pair ("\r\n") or as a single line feed character ("\n").| From 677d05416f1421dafa78e8162cecdf6c4d5eb1eb Mon Sep 17 00:00:00 2001 From: nanguil <114250457+nanguil@users.noreply.github.com> Date: Fri, 5 Jun 2026 18:31:13 -0700 Subject: [PATCH 3/3] Potential fix for pull request finding Suggestion for change to email claim description Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../customers/reference-oidc-claims-mapping-customers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md index e9677f2045f..7fb9178910c 100644 --- a/docs/external-id/customers/reference-oidc-claims-mapping-customers.md +++ b/docs/external-id/customers/reference-oidc-claims-mapping-customers.md @@ -29,7 +29,7 @@ Use the following table to map standard OpenID Connect claims to corresponding u |name|Display Name|Full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the end-user's locale and preferences.| |given_name|First Name|Given name(s) or first name(s) of the end-user.| |family_name|Last Name|Surname(s) or family name of the end-user.| -|email (required by default)|Email|Preferred e-mail address. Email is required by default, but you can [make it optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up) for external IdP sign-up scenarios.| +|email|Email|Preferred e-mail address. Email is required by default, but you can [make it optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up) for external IdP sign-up scenarios.| |email_verified|N/A|Indicates whether the identity provider has verified the end-user's e-mail address. `true` means the identity provider took affirmative steps to ensure the e-mail address was controlled by the end-user at the time the verification was performed. When email is required (the default), a verified email is needed for account creation — if `email_verified` is false, missing, or not mapped, account creation fails. If you've [configured email as optional](how-to-custom-oidc-federation-customers.md#make-email-optional-for-external-idp-sign-up), this claim is not required for account creation.| |phone_number|Phone number|The claim provides the phone number for the user.| |phone_number_verified|N/A|In the received ID token, the value of this claim is true if the end-user's phone number has been verified; otherwise, false. When this claim value is true, this means that your identity provider took affirmative steps to verify the phone number.|