Merge pull request #235150 from calvinlui/main

Azure AD optional claims updates

Author: prmerger-automator[bot]

articles/active-directory/develop/active-directory-optional-claims.md

@@ -107,6 +107,8 @@ Some optional claims can be configured to change the way the claim is returned.
 |                | `include_externally_authenticated_upn_without_hash` | Same as listed previously, except that the hash marks (`#`) are replaced with underscores (`_`), for example `[email protected]`|
 | `aud`          |                          | In v1 access tokens, this claim is used to change the format of the `aud` claim.  This claim has no effect in v2 tokens or either version's ID tokens, where the `aud` claim is always the client ID. Use this configuration to ensure that your API  can more easily perform audience validation. Like all optional claims that affect the access token, the resource in the request must set this optional claim, since resources own the access token.|
 |                | `use_guid`               | Emits the client ID of the resource (API) in GUID format as the `aud` claim always instead of it being runtime dependent. For example, if a resource sets this flag, and its client ID is `bb0a297b-6a42-4a55-ac40-09a501456577`, any app that requests an access token for that resource will receive an access token with `aud` : `bb0a297b-6a42-4a55-ac40-09a501456577`. </br></br> Without this claim set, an API could get tokens with an `aud` claim of `api://MyApi.com`, `api://MyApi.com/`, `api://myapi.com/AdditionalRegisteredField` or any other value set as an app ID URI for that API, and the client ID of the resource. |
+| `email`          |                          | Can be used for both SAML and JWT responses, and for v1.0 and v2.0 tokens. |
+|                | `replace_unverified_email_with_upn` (Preview)  | This is a public preview feature of Azure Active Directory. </br></br> In scenarios where email ownership is not verified, the `email` claim will return the user's home tenant UPN instead, unless otherwise stated below.   </br></br> For managed users, email is verified if the home tenant owns the email's domain as a custom domain name. For guest users, email is verified if either the home or resource tenants own the email's domain. If the user authenticates using Email OTP, MSA, or Google federation, the `email` claim will remain the same. If the user authenticates using Facebook or SAML/WS-Fed IdP federation, the `email` claim will not be returned.</br></br> The `email` claim is not guaranteed to be mailbox addressable, regardless of whether it is verified.  |
 
 #### Additional properties example