docs: Email not required for external IdP sign-up

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))
   - Email_verified
   - Phone number
   - Phone_number_verified
@@ -110,13 +110,76 @@ 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
+
+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:
 
 - 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)

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) 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").|