Entra Content Refactor: azure-ad-b2c rewrite to slim bridge page #36921
Description
Description
Addresses an individual article update for the greater Entra cotnent refactoring effort of part issue #36277
Recommendation: Rewrite azure-ad-b2c.md as a Slim Bridge Page
File: aspnetcore/security/authentication/azure-ad-b2c.md
Repository: dotnet/AspNetCore.Docs
Date: 2026-03-25
Problem Statement
The current azure-ad-b2c.md article is a full step-by-step tutorial (~200+ lines) that duplicates content already maintained in the Microsoft Entra and Azure AD B2C documentation. Azure AD B2C is being superseded by Microsoft Entra External ID for customers, and the article already includes an EOL support notice acknowledging this. Maintaining a parallel tutorial in the ASP.NET Core docs creates:
- Content duplication — Tenant creation, app registration, configuration, and testing steps are all covered authoritatively in Entra docs.
- Staleness risk — Code samples and configuration schemas drift out of sync with the Entra-maintained source of truth.
- Developer confusion — A full tutorial for a sunsetting product, sitting alongside an EOL banner, sends mixed signals.
Goals for the Rewrite
The article should be completely rewritten into a slim bridge page that:
- Eliminates content duplication between the ASP.NET Core docs and the Microsoft Entra documentation, favoring the Entra docs as the authoritative source for identity setup, configuration, and MFA.
- Creates clear entry points that guide ASP.NET Core developers to the appropriate Entra resource depending on whether they are starting a new project or maintaining an existing Azure AD B2C integration.
- Establishes a logical content flow where developers start in ASP.NET Core docs for framework-specific prerequisites and then transition to Entra and MFA docs for identity provider setup, tenant configuration, and testing procedures.
- Improves the developer experience by maintaining ASP.NET Core as the starting point while strategically directing users to authoritative Entra content, ensuring comprehensive coverage without redundancy.
What the Rewritten Article Should Contain
Section 1: Title and Front Matter
- Retain the existing
uid(security/authentication/azure-ad-b2c) so that allxreflinks and external URLs continue to resolve. - Update
ms.dateto the rewrite date. - Keep the title similar for SEO continuity (e.g., "Cloud authentication with Azure Active Directory B2C in ASP.NET Core").
Section 2: EOL and Migration Notice
- Include the existing shared include:
[!INCLUDE[](~/includes/azure-active-directory-b2c-eol-support-notice.md)] - This must be prominent and appear before any instructional content so developers immediately understand the product landscape.
Section 3: Recommended Path for New Projects
Purpose: Serve as the primary entry point for developers who have not yet chosen an identity provider.
Should contain:
- 2–3 sentences explaining that Microsoft Entra External ID for customers is the recommended CIAM solution for new ASP.NET Core applications.
- A direct link to the Entra External ID overview:
Microsoft Entra External ID for customers overview - A direct link to the Entra External ID ASP.NET Core quickstart:
Sample: Sign in users in a ASP.NET Core web app
Should NOT contain: Any tenant creation steps, app registration steps, or code. The Entra docs own that content.
Section 4: Guidance for Existing Azure AD B2C Projects
Purpose: Provide a clear path for developers maintaining apps that already use Azure AD B2C.
Should contain:
- 2–3 sentences acknowledging that Azure AD B2C remains supported for existing applications and that authoritative setup and configuration guidance is maintained in the Azure AD B2C documentation.
- Direct links to the key Azure AD B2C articles that the current tutorial duplicates:
| Topic currently duplicated in this article | Link to authoritative Entra/B2C documentation |
|---|---|
| Create a tenant | Tutorial: Create an Azure AD B2C tenant |
| Register a web application | Tutorial: Register a web application in Azure AD B2C |
| Configure authentication in an ASP.NET Core app | Configure authentication in a sample ASP.NET Core web app |
| Enable multi-factor authentication | Enable MFA in Azure AD B2C |
Should NOT contain: Step-by-step tenant creation, app registration, appsettings.json configuration, or run/test instructions. All of this is owned by the linked articles.
Section 5: ASP.NET Core Integration Checklist
Purpose: Retain the small amount of content that is genuinely ASP.NET Core-specific and not covered in Entra docs. This is where the article earns its place as the "starting point" in the ASP.NET Core doc set.
Should contain (brief checklist format, not a full tutorial):
- Install NuGet packages — State that
Microsoft.Identity.WebandMicrosoft.Identity.Web.UIare required. Include the twodotnet add packagecommands. This is the only code block needed in the entire article. - Configure services in
Program.cs— A short note (2–3 sentences) that the app must callAddMicrosoftIdentityWebAppandAddMicrosoftIdentityUI, with a link to Microsoft Identity Web documentation for the full API reference. - Add configuration — A single sentence stating that the
AzureADB2Csection inappsettings.jsonmust match the tenant and app registration values, and direct the reader to the Azure AD B2C configuration article linked in Section 4 for the complete schema and sample.
Should NOT contain:
- Full
appsettings.jsonsamples (duplicates Entra docs) _LoginPartial.cshtmlcode (trivial scaffolding covered by the Entra quickstart)_Layout.cshtmlmodifications (trivial scaffolding)- Complete
Program.csfile listing (duplicates Entra quickstart) - Run/test instructions (duplicates Entra quickstart)
Section 6: Additional Resources
Purpose: Replace the current verbose "Next steps" section with a concise, curated link list.
Should contain:
- Microsoft Entra External ID for customers overview
- Azure AD B2C documentation
- Customize the Azure AD B2C user interface
- Configure password complexity in Azure AD B2C
- Enable multi-factor authentication in Azure AD B2C
- Microsoft Graph API with Azure AD B2C
- ASP.NET Core authentication overview (internal xref)
Should NOT contain: Links to GitHub sample repos that may go stale or become unarchived.
Content to Remove
The following content from the current article should be entirely eliminated in the rewrite, as it is fully duplicated by the Entra documentation linked above:
| Current Section | Reason for Removal |
|---|---|
| Prerequisites (Azure account creation, .NET SDK installation) | Generic boilerplate repeated in every quickstart |
| Preparation — Create an Azure AD B2C tenant | Duplicates Create an Azure AD B2C tenant |
Preparation — Create a new Razor Pages app (dotnet new razor) |
Not B2C-specific; trivial command |
| Preparation — Create a web app registration | Duplicates Register a web application |
Modify the app — Full appsettings.json sample |
Duplicates Configure authentication in sample web app |
Modify the app — _LoginPartial.cshtml (full code listing) |
Trivial scaffolding covered by Entra quickstart |
Modify the app — _Layout.cshtml (partial tag insertion) |
Trivial scaffolding |
Modify the app — Full Program.cs walkthrough |
Duplicates Entra quickstart and Microsoft Identity Web docs |
| Run the app (launch profile, browse, test sign-in/sign-out) | Duplicates Entra quickstart |
| Next steps (verbose bulleted list) | Replaced by concise "Additional Resources" section |
Associated File Cleanup
The following sample files are referenced via :::code directives in the current article and will no longer be needed after the rewrite. They should be deleted:
azure-ad-b2c/sample/appsettings-b2c-userflow.jsonazure-ad-b2c/sample/Program.csazure-ad-b2c/sample/Pages/Shared/_LoginPartial.cshtmlazure-ad-b2c/sample/Pages/Shared/_Layout.cshtml
Additionally, verify that ~/includes/azure-active-directory-b2c-eol-support-notice.md is up to date and references Microsoft Entra External ID as the recommended successor.
Expected Outcome
| Metric | Current State | After Rewrite |
|---|---|---|
| Article length | ~200+ lines (full tutorial) | ~50–60 lines (bridge page) |
| Content duplicated with Entra docs | ~95% | ~0% |
| Maintenance burden | High (code samples, config samples, multi-step tutorial) | Low (links and a short checklist) |
| Developer experience | Confusing (full tutorial for sunsetting product alongside EOL banner) | Clear (ASP.NET Core starting point → Entra docs for setup → return for framework integration) |
| Content flow | Linear tutorial that never leaves ASP.NET Core docs | ASP.NET Core entry point → Entra docs for identity setup → back to checklist for framework wiring |
| Backward compatibility | N/A | Fully preserved (uid and file path unchanged) |
Content Flow Summary
The rewritten article establishes this developer journey:
┌─────────────────────────────────┐
│ ASP.NET Core Docs (this page) │
│ "Cloud auth with Azure AD B2C" │
├─────────────────────────────────┤
│ 1. See EOL notice │
│ 2. New project? → Entra Ext ID ─┼──→ Entra External ID docs
│ 3. Existing B2C? → See links ──┼──→ Azure AD B2C docs (tenant, registration, config, MFA)
│ 4. ASP.NET Core checklist: │
│ • Install NuGet packages │
│ • Wire up Program.cs │
│ • Point to config article ──┼──→ Entra config article
│ 5. Additional resources ──┼──→ Entra docs (UI, passwords, MFA, Graph)
└─────────────────────────────────┘
This flow keeps ASP.NET Core as the developer's starting point, provides framework-specific guidance where it's uniquely valuable, and delegates all identity-provider setup, configuration detail, and testing procedures to the authoritative Entra documentation.
Page URL
Content source URL
Document ID
ef34ebdf-977a-b797-e263-cb32c1643272
Platform Id
556700a1-ba2e-30e2-f594-a597f19ab259
Article author
Metadata
- ID: 765e611b-a170-db1a-fa50-2771d79b2732
- PlatformId: 556700a1-ba2e-30e2-f594-a597f19ab259
- Service: aspnet-core
- Sub-service: security