Update Facebook auth setup guide with official docs links and email permission guidance

[Copilot]

The Facebook auth article omitted guidance about the email permission requirement and contained outdated step-by-step UI instructions with stale screenshots. The ASP.NET Core FacebookOptions requests the email scope by default, but if the Facebook app hasn't granted that permission, sign-in fails or the email claim is missing from the authenticated user.

Changes

• "Create the app in Facebook" section: Replaced the outdated step-by-step Facebook Developer portal instructions and screenshots with links to Facebook's official documentation:
  • Facebook App Registration for creating the app and obtaining App ID / App Secret.
  • Facebook Login for Web for configuring Facebook Login and OAuth redirect URIs.
  • Facebook Login Permissions for enabling the email permission, with a note that the ASP.NET Core middleware requests the email scope by default and authentication will fail or the email claim will be missing if this permission is not configured.
• Troubleshooting section: Added a bullet pointing developers to check email permission status when sign-in fails or email is missing post-authentication.
• Removed unused screenshots: Deleted 6 stale Facebook UI screenshot files (FBLogin.png, FBMyApps.png, FBNewAppId.png, FBOAuthSetup.png, FBProductSetup.png, FBSkipQuickStart.png) that are no longer referenced.
• Metadata: Updated ms.date, added ai-usage: ai-assisted, removed the sfi-image-nochange custom tag, and fixed front matter key ordering to alphabetical.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Missing config info for Facebook auth</issue_title>
<issue_description>### Description

[Enter feedback here]
When configuring facebook authentication you must request email permissions when configuring the app on facebook.
This appears not to be the default.
Without email permissions, you receive a "something went wrong" error.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/security/authentication/social/facebook-logins?view=aspnetcore-8.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/security/authentication/social/facebook-logins.md

Document ID

d22d616f-907e-ae62-1f43-88ad176a87d4

Article author

@Rick-Anderson</issue_description>

Comments on the Issue (you are @copilot in this section)

@wadepickett # Issue Analysis: Missing Config Info for Facebook Auth Email Permissions

Issue Summary

This is a valid issue. The article on Facebook external login setup in ASP.NET Core is missing guidance about configuring email permissions on the Facebook Developer portal when setting up the Facebook app.

Issue Status

This issue has not been addressed in the latest version of the article. The current main branch source file (facebook-logins.md) contains no mention of email permissions on the Facebook Developer portal, nor any troubleshooting guidance related to this scenario.

Target Framework Version

• The article covers ASP.NET Core 3.0+ (monikerRange: '>= aspnetcore-3.0').
• The code sample for >= aspnetcore-6.0 references ProgramFacebook.cs (minimal hosting model).
• The code sample for < aspnetcore-6.0 uses the Startup.ConfigureServices pattern.
• The ms.date is 12/08/2021, indicating this article has not been updated in over 4 years.

Verification of the Issue

The ASP.NET Core FacebookOptions constructor adds "email" to the OAuth Scope by default. The middleware therefore requests the email scope from Facebook during the OAuth flow, but this only works if the Facebook app itself has the email permission enabled in the Facebook Developer portal. Without it, users may see a Facebook-side error page, an ASP.NET Core authentication failure, or a successful login with a missing email claim that causes downstream Identity registration errors.

Gap in the Article

The "Create the app in Facebook" section (lines 21–59) walks through creating the app, setting up Facebook Login, and configuring OAuth redirect URIs, but never mentions that the developer must enable the email permission in the Facebook app settings.

Scope of the Fix

Documentation-only. No code file changes are needed. ProgramFacebook.cs and StartupAccessDeniedPath.cs do not require modification because the ASP.NET Core SDK already adds email to the scope by default.

Files to Change

1. aspnetcore/security/authentication/social/facebook-logins.md

Source: facebook-logins.md

Change Area 1: "Create the app in Facebook" section (around lines 36–53)

Add a step after the Facebook Login product setup instructions (after line 53, "Select Save Changes.") instructing the developer to configure email permissions:

Suggested addition (after line 53):

• In the Facebook Developer portal, navigate to your app's permissions settings and ensure the email permission is enabled. The ASP.NET Core Facebook authentication middleware requests the email scope by default. If this permission is not configured on the Facebook app, authentication will fail or the user's email claim will be missing.

Change Area 2: "Troubleshooting" section (lines 142–145)

Add a troubleshooting entry for the missing email permission scenario:

Suggested addition (after line 145):

• If you receive errors during Facebook sign-in or the user's email is missing after login, verify that the email permission is enabled for your Facebook app in the Facebook Developer portal.

Impact Assessment

• Changes limited to a single markdown file (facebook-logins.md).
• No code sample files need modification.
• Changes apply across all moniker versions.
• The ms.date in the front matter should also be updated.</comment_new>

• Fixes Missing config info for Facebook auth #31508

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Internal previews

📄 File	🔗 Preview link
aspnetcore/security/authentication/social/facebook-logins.md	Facebook external login setup in ASP.NET Core

[wadepickett]

@copilot, The step-by-step Facebook Developer portal instructions and screenshots (lines 25–59) should be replaced with a link to Facebook's own setup documentation so the guidance stays current. The section should direct developers to:

• Facebook App Registration for creating the app and obtaining App ID / App Secret.
• Facebook Login for Web for configuring Facebook Login and OAuth redirect URIs.
• Facebook Login Permissions for enabling the email permission, with a note that the ASP.NET Core middleware requests the email scope by default and authentication will fail or the email claim will be missing if this permission is not configured.

The original images that Facebook UI images that are no longer used should also be removed.

[Copilot]

@copilot, The step-by-step Facebook Developer portal instructions and screenshots (lines 25–59) should be replaced with a link to Facebook's own setup documentation so the guidance...

Done in commit c732c00. The "Create the app in Facebook" section now links to Facebook's official docs for App Registration, Facebook Login for Web, and Facebook Login Permissions (with a note that the email scope is requested by default). The 6 unused Facebook UI screenshot files have been removed.

[wadepickett]

Approved after several changes to rely more on the up to date Facebook site guidance instead.

[meaghanlewis]

These changes LGTM.