Clarify verified domain email and ExternalIdentity access limitations (#61062)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: N-Usha <25389593+N-Usha@users.noreply.github.com>
Co-authored-by: Usha N <n-usha@github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>

Author: 3 people

content/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/viewing-people-in-your-enterprise.md

@@ -109,6 +109,9 @@ You may be able to view the email addresses for members of your enterprise on ei
 
 * If you verify a domain for your enterprise, you can view members' email addresses for the verified domain. For more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise).
 
+  > [!NOTE]
+  > Email addresses for verified domains are not returned in a guaranteed order. If a member has email addresses for multiple verified domains, old or stale email addresses may remain after an IdP change. The list of verified domain email addresses cannot reliably identify the member's canonical or current corporate email address.
+
 * If you don't use {% data variables.product.prodname_emus %}, and you also don't configure SAML single sign-on (SSO), members access your enterprise's resources on {% data variables.product.github %} solely using a personal account. {% data reusables.saml.personal-accounts-determine-email-visibility %}
 
 If you use {% data variables.product.prodname_emus %}, verify a domain, or configure SAML SSO for your enterprise, you may be able to view the email addresses in one or more of the following ways.
@@ -119,6 +122,8 @@ If you use {% data variables.product.prodname_emus %}, verify a domain, or confi
    * `GitHub com saml name`: The `NameID` from the user's linked SAML identity, which is typically the user's email address (for more information, see [AUTOTITLE](/admin/identity-and-access-management/using-saml-for-enterprise-iam/saml-configuration-reference))
    * `GitHub com verified domain emails`: Email addresses for any verified domains (for more information, see [AUTOTITLE](/admin/configuration/configuring-your-enterprise/verifying-or-approving-a-domain-for-your-enterprise))
 
+     The `GitHub com verified domain emails` value is unordered. Emails may be returned in a non-deterministic order, and you cannot request priority, sorting, or filtering for the user's current email address.
+
    For more information, see [AUTOTITLE](/admin/user-management/managing-users-in-your-enterprise/exporting-membership-information-for-your-enterprise).
 {% data reusables.saml.use-api-to-get-externalidentity %}
 

data/reusables/saml/use-api-to-get-externalidentity.md

@@ -1 +1,4 @@
 1. Use the GraphQL API to retrieve the `ExternalIdentity` for each member. For more information, see [AUTOTITLE](/graphql/overview/about-the-graphql-api) and [AUTOTITLE](/graphql/reference/objects#externalidentity) in the GraphQL API documentation.
+
+   > [!NOTE]
+   > Access to external identities depends on whether SAML is configured at the organization or enterprise level. Organization-level external identities are available to organization owners, organization owner {% data variables.product.pat_generic_plural %} with the `read:org` or `admin:org` scope, and {% data variables.product.prodname_github_app %} installation tokens with read or write access to members when the app is installed on the organization. Enterprise-level external identities require an enterprise owner {% data variables.product.pat_generic %} with the `read:enterprise` or `admin:enterprise` scope. {% data variables.product.prodname_github_apps %} cannot access enterprise-level external identities, including enterprise-level SAML identities for {% data variables.product.prodname_ghe_cloud %} with personal user accounts.

src/graphql/data/ghec/schema.docs.graphql

@@ -69460,7 +69460,7 @@ type User implements Actor & Agentic & Node & PackageOwner & ProfileOwner & Proj
   ): Organization
 
   """
-  Verified email addresses that match verified domains for a specified organization the user is a member of.
+  Verified email addresses that match verified domains for a specified organization the user is a member of. Results are unordered. There is no way to specify ordering, priority, or filtering, and this field should not be used to determine a user's canonical or current corporate email in multi-domain contexts.
   """
   organizationVerifiedDomainEmails(
     """