Repository navigation
Document the Microsoft Entra ID integration for Aspire 17.0 - #2086
Open
Eric Erhardt (eerhardt) wants to merge 2 commits into
Open
Eric Erhardt (eerhardt) wants to merge 2 commits into
Eric Erhardt (eerhardt) wants to merge 2 commits into
Conversation
Add a multi-page Microsoft Entra ID integration section under integrations/security/microsoft-entra-id covering the hosting package, redirect URIs and sign-in, client credentials, exposing and calling APIs, application roles, existing registrations, infrastructure customization, lifecycle and permissions, and a web-to-API walkthrough. Consolidates and supersedes the independent draft PRs #1928, #1934, #1944, #1964, #1973, #1991, #2027, #2028, #2031, and #2043. Every claim was verified against microsoft/aspire. Also adds the sidebar group, an Entra row in the Azure provisioning package table, and cross-links from related Azure pages. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Eric Erhardt (eerhardt)
requested a review
from David Pine (IEvangelist)
as a code owner
November 7, 2026 00:16
This was referenced Nov 7, 2026
This was referenced Nov 7, 2026
![aspire-repo-bot[bot]](https://avatars.githubusercontent.com/in/3085065?s=60&v=4){kind=small}
| - [Azure user-assigned managed identities](/integrations/cloud/azure/user-assigned-identity/) | ||
| - [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity-platform/) | ||
| - [Bicep templates for Microsoft Graph](https://learn.microsoft.com/graph/templates/bicep/overview-bicep-templates-for-graph) | ||
| - [Securing .NET Aspire apps with Microsoft Entra ID](https://devblogs.microsoft.com/aspire/securing-dotnet-aspire-apps-with-microsoft-entra-id/) |
Contributor
There was a problem hiding this comment.
Use "Aspire" instead of ".NET Aspire".
Suggested change
| - [Securing .NET Aspire apps with Microsoft Entra ID](https://devblogs.microsoft.com/aspire/securing-dotnet-aspire-apps-with-microsoft-entra-id/) | |
| - [Securing Aspire apps with Microsoft Entra ID](https://devblogs.microsoft.com/aspire/securing-dotnet-aspire-apps-with-microsoft-entra-id/) |
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved documentation errors can break authentication and consent flows, block frontend startup, prevent preview-package restoration, and mislead readers about certificate rollover requirements.
5 open issues
What changed in this PR
Adds a consolidated Microsoft Entra ID integration guide for Aspire 17.0, replacing overlapping draft documentation and connecting it to existing Azure guidance.
Changes:
- Adds nine pages covering registration setup, authentication, credentials, API permissions, roles, and lifecycle management.
- Provides TypeScript and C# AppHost examples with preview limitations and deployment requirements.
- Adds sidebar navigation, a provisioning-package entry, and related Azure cross-links.
| File | Description |
|---|---|
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/secure-web-and-api.mdx |
Adds a local-to-Azure authentication walkthrough. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/redirect-uris-and-sign-in.mdx |
Covers callbacks, audiences, and sovereign clouds. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/lifecycle-and-permissions.mdx |
Explains permissions, cleanup, and troubleshooting. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/index.mdx |
Introduces installation, configuration, and preview status. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/expose-and-call-apis.mdx |
Documents scopes, consent, and downstream API calls. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/existing-registrations.mdx |
Explains references to externally managed registrations. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/customize-infrastructure.mdx |
Demonstrates Microsoft Graph infrastructure customization. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/client-credentials.mdx |
Covers secrets, certificates, and identity federation. |
src/frontend/src/content/docs/integrations/security/microsoft-entra-id/app-roles.mdx |
Documents role declarations and managed identity assignments. |
src/frontend/src/content/docs/integrations/cloud/azure/user-assigned-identity.mdx |
Links to Entra application-role assignments. |
src/frontend/src/content/docs/integrations/cloud/azure/local-provisioning.mdx |
Links to the Entra integration overview. |
src/frontend/src/content/docs/integrations/cloud/azure/customize-resources.mdx |
Adds the Entra provisioning package and guidance. |
src/frontend/src/content/docs/integrations/cloud/azure/azure-key-vault/azure-key-vault-host.mdx |
Links to certificate credentials and automatic access grants. |
src/frontend/config/sidebar/integrations.topics.ts |
Adds the Microsoft Entra ID navigation group. |
Review effort: Balanced
| }) | ||
| .publishWithAppRoleAssignment(worker, ["Orders.Read"]); | ||
|
|
||
| const api = await builder.addContainer("api", "my-api-image"); |
|
|
||
| ## Send the certificate chain | ||
|
|
||
| `WithSendX5C` sends the `x5c` claim, which carries the public certificate, with token requests. This enables certificate rollover without redeploying the app. It applies only to certificate-based credentials and increases the size of each token request, so it's opt-in. |
|
|
||
| Add the [📦 Aspire.Hosting.Azure.EntraId](https://www.nuget.org/packages/Aspire.Hosting.Azure.EntraId) package to your AppHost: | ||
|
|
||
| <InstallPackage packageName="Aspire.Hosting.Azure.EntraId" /> |
|
|
||
| app.UseAuthentication(); | ||
| app.UseAuthorization(); | ||
| app.MapControllers(); |
| ```csharp title="Web/Program.cs" | ||
| builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme) | ||
| .AddMicrosoftIdentityWebApp(builder.Configuration) | ||
| .EnableTokenAcquisitionToCallDownstreamApi() |
Contributor
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the Microsoft Entra ID hosting integration (epic microsoft/aspire#21060) as one consolidated set of pages under
integrations/security/microsoft-entra-id/. It replaces ten independent bot-written draft PRs that overlapped, edited the same files, and in places contradicted the shipped API. Every claim was checked againstmicrosoft/aspire(README, code,[AspireExport]attributes, polyglot fixtures, tests, and the end-to-end deployment tests).New pages:
index)x5cDownstreamApis, consent, pre-authorization, Graph and custom APIsWithAppRole, retirement rules,PublishWithAppRoleAssignmentfor managed identitiesAddExistingEntraApplicationvsAsExistingApplication, supported vs rejected settingsConfigureInfrastructure, tags,serviceManagementReference, experimentalAspire.Hosting.Azure.Provisioning.EntraId(ASPIREAZUREPROVISIONING001)Other changes: sidebar group under Security & identity, a Microsoft Entra ID row in the Azure provisioning package table, and cross-links from the local provisioning, user-assigned identity, and Key Vault pages.
Superseded drafts (closed after this PR opens): #1928, #1934, #1944, #1964, #1973, #1991, #2027, #2028, #2031, #2043.
Consolidation notes and assumptions
apphost.tstitles, the wrongsyncKey, C# before TypeScript, a nonexistentprereleaseprop onInstallPackage, an unverifiedshortName, aligned fluent indentation, the stale "add URL callbacks beforeWithRedirectUris" note (resolution now waits for all URL customizations), and a claim thatlocal-provisioning.mdxdocuments "Missing subscription configuration".twoslash-annotated because the bundled twoslash data predates the Entra package. The method names and option shapes were verified againstapphost.mtsand the[AspireExport]attributes. C#-only APIs (WithCredential,EntraIdApi,EntraIdApiPermission,EntraIdAppRole) show C# only or use the TypeScript DTO equivalents.integrations.topics.ts.integration-docs.jsonmappings were intentionally not added.reconcileIntegrationDocsprunes official-package entries missing fromaspire-integrations.json, sopnpm test:unit:structured-datafails until the packages appear on NuGet. They can be added by the integrations updater afterwards.<ApiReference>components are used because no generated API data exists for these packages yet.Open questions and unverifiable claims
AzureAdMicrosoft.Identity.Web snippets were checked against Microsoft.Identity.Web source (AddMicrosoftIdentityMessageHandler(IConfiguration, string),EnableTokenAcquisitionToCallDownstreamApi,AddMicrosoftIdentityWebApi) but not executed end to end.WithAllowWebApiToBeAuthorizedByACLfollows the shipped end-to-end deployment test. The exact Microsoft.Identity.Web rejection behavior for tokens withoutrolesis from that test and the option's XML doc.Third-party links and affiliations
None. All added links point to Microsoft-owned sites (learn.microsoft.com, entra.microsoft.com, aka.ms, devblogs.microsoft.com, nuget.org package pages) and the existing aspire.dev docs.
Validation
Run from
src/frontend;pnpm buildwas not run, per repository policy:pnpm install --frozen-lockfile: passedpnpm test:unit:structured-data: passed (5 files, 99 tests)pnpm exec vitest run --config vitest.config.ts: passed (97 files, 1398 passed, 1 skipped), includingseo-lengths,typescript-first-apphost-tabs, andtwoslash-blockspnpm exec eslint config/sidebar/integrations.topics.ts --max-warnings 0: passedpnpm exec prettier --write config/sidebar/integrations.topics.ts: appliedOverviewheadings, non-TypeScript-first tabs, badsyncKey/titles, and missing trailing slashes: clean.starlight-icons/*andtwoslash/aspire.d.tswere restored and are not in the commit