Microsoft Entra ID integration
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
The Microsoft Entra ID hosting integration models Microsoft Entra ID application registrations in your AppHost. Aspire can create a registration and its service principal, or you can reference a registration that already exists. Either way, the integration passes the registration’s settings to the resources that reference it as environment variables.
The integration configures registrations and the settings that apps read. It doesn’t install authentication middleware or protect routes. Use Microsoft.Identity.Web or the equivalent library for your app’s language to sign users in and validate tokens, and validate scopes or roles in your API.
Prerequisites
Section titled “Prerequisites”- You need a Microsoft Entra ID tenant.
- To create registrations, you need an Azure subscription, permission to deploy to a resource group, permission to create application registrations and service principals in the subscription’s tenant, and the Azure CLI with Bicep 0.36.1 or later. Tenant policy can restrict registration creation.
- To reference existing registrations, you need an app registration created in the Microsoft Entra admin center. This path needs no Azure or Microsoft Graph access.
The first Bicep compilation downloads the Microsoft Graph Bicep extension from mcr.microsoft.com, so that registry must be reachable when Aspire creates registrations.
Hosting integration
Section titled “Hosting integration”Add the 📦 Aspire.Hosting.Azure.EntraId package to your AppHost:
aspire add azure-entraidDie Aspire CLI ist interaktiv; das passende Suchergebnis wählen, wenn gefragt:
Select an integration to add:
> azure-entraid (Aspire.Hosting.Azure.EntraId)> Other results listed as selectable options...#:package Aspire.Hosting.Azure.EntraId@*<PackageReference Include="Aspire.Hosting.Azure.EntraId" Version="*" />The integration is available in C#, TypeScript, Python, Go, Java, and Rust AppHosts with the same behavior. Method names follow each language’s conventions, and optional arguments are passed as options objects or keyword arguments. The examples on these pages use C# and TypeScript.
The examples add .NET projects with AddDotnetProject, which comes from the Dotnet hosting integration.
Add a registration and reference it
Section titled “Add a registration and reference it”AddEntraIdApplication adds a registration that Aspire creates. Reference it from an app with WithReference to give that app the registration’s settings.
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const entraApi = await builder.addEntraIdApplication("entra-api");
const entraWeb = await builder.addEntraIdApplication("entra-web");
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");await api.withReference(entraApi);
const web = await builder.addDotnetProject("web", "../Web/Web.csproj");await web.withReference(entraWeb);
await entraWeb.withRedirectUris(await web.getEndpoint("https"), { callbackPaths: ["/signin-oidc", "/signout-callback-oidc"],});
await builder.build().run();var builder = DistributedApplication.CreateBuilder(args);
var entraApi = builder.AddEntraIdApplication("entra-api");
var entraWeb = builder.AddEntraIdApplication("entra-web");
builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(entraApi);
var web = builder.AddDotnetProject("web", "../Web/Web.csproj") .WithReference(entraWeb);
entraWeb.WithRedirectUris(web.GetEndpoint("https"), "/signin-oidc", "/signout-callback-oidc");
// After adding all resources, run the app...builder.Build().Run();WithRedirectUris derives the sign-in and sign-out callbacks from the web app’s HTTPS endpoint, so you don’t hard-code a port or host name. For more information, see Redirect URIs and sign-in.
When the AppHost starts, Aspire creates the registration and its service principal. The registration is created in the subscription’s tenant, which isn’t necessarily your account’s home tenant. Configure local Azure provisioning with your subscription and location, and sign in to the Azure CLI before you run the AppHost.
The registration appears in the dashboard as a resource:
- When it’s ready, it reports Running, links to the tenant’s OpenID Connect discovery document, and shows its tenant ID, client ID, and other settings as properties. In the Azure public cloud and national clouds, it also links to the app registration in the Azure portal.
- If a setting is invalid, it reports Failed to start, and its console logs explain why. If Azure provisioning isn’t configured, it reports Missing subscription configuration. To resolve these and other errors, see Troubleshoot Entra ID errors.
If tenant policy prevents creating registrations, use AddExistingEntraIdApplication for a configuration-only reference.
Settings that apps receive
Section titled “Settings that apps receive”WithReference injects settings as environment variables. The names depend on the kind of app.
- .NET projects receive keys in the form
AzureAd__{Key}, such asAzureAd__TenantIdandAzureAd__ClientId. .NET configuration maps them to theAzureAdsection that Microsoft.Identity.Web reads. - Other resources receive uppercase snake-case names that start with the registration’s resource name, such as
ENTRA_API_TENANT_IDandENTRA_API_CLIENT_IDfor theentra-apiresource.
A .NET project reads the settings as ordinary configuration. For example, an API validates tokens with the injected AzureAd section:
builder.Services.AddAuthentication() .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));Other apps read the variables and map them into their authentication library’s options. Adding a reference doesn’t install or configure an authentication library.
| Setting | When it’s present |
|---|---|
Instance, TenantId, ClientId | Always. |
AppHomeTenantId | The sign-in audience allows other tenants. TenantId then holds organizations, common, or consumers. |
ClientCredentials entries | A credential is configured. See client credentials. |
Scopes | The registration exposes enabled scopes. See expose and call APIs. |
DownstreamApis entries | The registration declares permissions to other APIs. For .NET projects, the DownstreamApis section is a sibling of AzureAd. |
Audiences entries | WithAudience is called. |
ClientCapabilities, SendX5C, AllowWebApiToBeAuthorizedByACL, ExtraQueryParameters | The matching WithClientCapability, WithSendX5C, WithAllowWebApiToBeAuthorizedByACL, or WithExtraQueryParameter method is called. |
Change the environment variable names
Section titled “Change the environment variable names”Use connectionName to change the prefix for one reference. Each referencing app chooses its own name without affecting other references to the same registration.
const worker = await builder.addContainer("worker", "my-worker-image");await worker.withReference(entraApi, { connectionName: "ENTRA" });var worker = builder.AddContainer("worker", "my-worker-image") .WithReference(entraApi, connectionName: "ENTRA");This reference produces names such as ENTRA_TENANT_ID and ENTRA_CLIENT_ID. For .NET projects, a colon in the connection name becomes a double underscore, so Entra:Web produces Entra__Web__ClientId.
For .NET projects, DownstreamApis entries ignore the connection name. For other resources, they’re nested under it, such as ENTRA_DOWNSTREAM_APIS_.... To change the DownstreamApis prefix, see Settings that the caller receives.
Run and publish behavior
Section titled “Run and publish behavior”The same registration can behave differently when you run the AppHost and when you publish or deploy it.
| Behavior | Run | Publish and deploy |
|---|---|---|
| Created registration | Created through Azure provisioning when the AppHost starts. | Deployed with the rest of your Azure resources. |
| Existing registration | Configuration only. Aspire doesn’t deploy Bicep or query Microsoft Graph. | Configuration only, and excluded from the publish manifest. |
| Redirect URIs from an endpoint | Uses the endpoint’s finalized browser URL. | Uses the compute environment’s host and requires TLS. |
| Local developer certificate | Provisions a short-lived certificate credential. | Isn’t used. |
| Managed identity federation that Aspire creates | Isn’t used. | Trusts the app’s user-assigned managed identity. |
| Managed identity federation that you configured | Applies. | Applies. |
| App-role assignments to managed identities | Isn’t used. | Assigned during deployment. |
For the full lifecycle, required permissions, and known limitations, see lifecycle and permissions.