Aspirerelease/17.0
Watch Aspire live streamsDokumentasiCoba Aspire

Microsoft Entra ID integration

Konten ini belum tersedia dalam bahasa Anda.

🧪 Preview

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.

  • 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.

Add the 📦 Aspire.Hosting.Azure.EntraId package to your AppHost:

Aspire CLI — Tambahkan paket Aspire.Hosting.Azure.EntraId
aspire add azure-entraid

Aspire CLI interaktif; pilih hasil pencarian yang sesuai saat diminta:

Aspire CLI — Contoh keluaran
Select an integration to add:
> azure-entraid (Aspire.Hosting.Azure.EntraId)
> Other results listed as selectable options...

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.

AddEntraIdApplication adds a registration that Aspire creates. Reference it from an app with WithReference to give that app the registration’s settings.

apphost.mts
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();

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.

WithReference injects settings as environment variables. The names depend on the kind of app.

  • .NET projects receive keys in the form AzureAd__{Key}, such as AzureAd__TenantId and AzureAd__ClientId. .NET configuration maps them to the AzureAd section 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_ID and ENTRA_API_CLIENT_ID for the entra-api resource.

A .NET project reads the settings as ordinary configuration. For example, an API validates tokens with the injected AzureAd section:

Program.cs
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.

SettingWhen it’s present
Instance, TenantId, ClientIdAlways.
AppHomeTenantIdThe sign-in audience allows other tenants. TenantId then holds organizations, common, or consumers.
ClientCredentials entriesA credential is configured. See client credentials.
ScopesThe registration exposes enabled scopes. See expose and call APIs.
DownstreamApis entriesThe registration declares permissions to other APIs. For .NET projects, the DownstreamApis section is a sibling of AzureAd.
Audiences entriesWithAudience is called.
ClientCapabilities, SendX5C, AllowWebApiToBeAuthorizedByACL, ExtraQueryParametersThe matching WithClientCapability, WithSendX5C, WithAllowWebApiToBeAuthorizedByACL, or WithExtraQueryParameter method is called.

Use connectionName to change the prefix for one reference. Each referencing app chooses its own name without affecting other references to the same registration.

apphost.mts
const worker = await builder.addContainer("worker", "my-worker-image");
await worker.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.

The same registration can behave differently when you run the AppHost and when you publish or deploy it.

BehaviorRunPublish and deploy
Created registrationCreated through Azure provisioning when the AppHost starts.Deployed with the rest of your Azure resources.
Existing registrationConfiguration only. Aspire doesn’t deploy Bicep or query Microsoft Graph.Configuration only, and excluded from the publish manifest.
Redirect URIs from an endpointUses the endpoint’s finalized browser URL.Uses the compute environment’s host and requires TLS.
Local developer certificateProvisions a short-lived certificate credential.Isn’t used.
Managed identity federation that Aspire createsIsn’t used.Trusts the app’s user-assigned managed identity.
Managed identity federation that you configuredApplies.Applies.
App-role assignments to managed identitiesIsn’t used.Assigned during deployment.

For the full lifecycle, required permissions, and known limitations, see lifecycle and permissions.