Aspirerelease/17.0

Existing Entra ID registrations

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

Many teams manage app registrations outside the AppHost, for example because a central identity team owns them. Aspire can reference such a registration so that your apps receive its settings. Aspire never creates, queries, or modifies an existing registration, so you configure the registration itself in the Microsoft Entra admin center.

You supply the Directory (tenant) ID and the Application (client) ID from the registration’s Overview page. Use AddExistingEntraIdApplication when you don’t want Aspire to set up Azure provisioning for the registration. You can mix existing registrations with registrations that Aspire creates in the same AppHost.

apphost.mts
import { createBuilder } from './.aspire/modules/aspire.mjs';
const builder = await createBuilder();
const tenantId = await builder.addParameter("entra-tenant-id");
const apiClientId = await builder.addParameter("entra-api-client-id");
const entraApi = await builder.addExistingEntraIdApplication("entra-api", tenantId, apiClientId);
const api = await builder.addDotnetProject("api", "../Api/Api.csproj");
await api.withReference(entraApi);
await builder.build().run();

Each ID accepts a literal value or a parameter. In TypeScript, you can mix them:

apphost.mts
const clientId = await builder.addParameter("entra-client-id");
const clientSecret = await builder.addParameter("entra-secret", { secret: true });
const entraApi = await builder.addExistingEntraIdApplication(
"entra-api", "aaaabbbb-0000-cccc-1111-dddd2222eeee", clientId)
.withClientSecret(clientSecret);
await builder.addExecutable("worker", "node", ".", ["worker.mjs"])
.withReference(entraApi, { connectionName: "AUTH" });

In C#, the overloads take two literals or two parameters.

The tenant ID must be a GUID or a domain name such as contoso.onmicrosoft.com, and the client ID must be a GUID. Pass the home tenant here, not a sign-in keyword such as organizations, common, or consumers. To let accounts from other tenants sign in, keep the home tenant and call WithSignInAudience. For more information, see Redirect URIs and sign-in.

Aspire validates literal IDs when the call runs, and throws for an invalid value. It validates parameter values at startup. An invalid or missing parameter value puts the resource in the FailedToStart state and logs the reason.

You can also convert an AddEntraIdApplication resource with AsExistingApplication. The two approaches differ in the Azure setup that they keep.

ApproachAzure provisioningUse it when
AddExistingEntraIdApplicationNot enabledThe AppHost needs only the registration’s settings. It needs no Azure or Microsoft Graph access.
AddEntraIdApplication(...).AsExistingApplication(...)KeptYou start with a created registration and later point it at an existing one.

AsExistingApplication keeps the Azure setup that AddEntraIdApplication adds, so deployment can still require Azure authentication and provisioning configuration. Other Azure resources in the same AppHost keep their normal provisioning behavior in both approaches.

apphost.mts
const entraApi = await builder.addEntraIdApplication("entra-api")
.asExistingApplication(tenantId, apiClientId);

AsExistingApplication throws when you already applied registration-only configuration, such as redirect URIs or app roles. Remove that configuration first.

Nothing is deployed for an existing registration. The apps that reference it still receive its settings.

Settings that describe how an app uses the registration still work. They must match the registration, because they don’t register anything. Settings that change a registration throw an InvalidOperationException that explains what to configure yourself.

SettingExisting registration
WithClientSecret, WithClientCapability, WithSendX5C, and the certificate and signed assertion credentialsSupported. The registration must already trust the credential.
WithFederatedManagedIdentityCredentialSupported. Configure the trust yourself first.
WithAudience, WithSignInAudience, WithInstanceSupported. They affect only the referencing app’s configuration.
WithApplicationIdUri with a URI, and WithScopeSupported. They describe an existing API.
WithApiPermissionsSupported. It only produces the DownstreamApis configuration.
WithRedirectUris, WithIdTokenIssuanceThrows. Configure these in the registration’s Authentication settings.
WithOwners, WithApplicationOwners, WithServicePrincipalOwnersThrows.
WithAppRole, PublishWithAppRoleAssignmentThrows.
WithAdminConsent and WithPreAuthorizedApplicationThrows. For Microsoft Graph and other external APIs, this includes the withExternalApiAdminConsent method in TypeScript.
WithApplicationIdUri without a URIThrows. Aspire can’t infer an existing API’s URI.
RunWithLocalDeveloperCertificateCredential, PublishWithFederatedManagedIdentityCredentialThrows. Aspire can’t register a certificate or create a federated credential on an existing registration.

A registration that Aspire creates can still consent to an existing API or pre-authorize an existing client, because the existing registration isn’t modified.

To reference an existing API’s scopes, pass the URI that the registration already defines to WithApplicationIdUri, and describe each scope with WithScope. Set the scope’s ID to the registered scope ID when a registration that Aspire creates declares permissions to the scope.

apphost.mts
const entraApi = await builder.addExistingEntraIdApplication("entra-api", tenantId, apiClientId)
.withApplicationIdUri({ applicationIdUri: "api://contoso-orders" })
.withScope("Weather.Read", "Allows the app to read weather forecasts.", {
id: "5d1f7b84-3c2e-4a6e-9a1d-0b8f2c3d4e5f",
});
// entraWeb is a created registration, as in the expose and call APIs article.
await entraWeb.withApiPermissions(entraApi, ["Weather.Read"]);

GetScopeUri requires an application ID URI.

An existing registration that calls an API needs a credential that it already trusts. Pass the credential with a method such as WithClientSecret or a certificate credential. For a managed identity, create the federated credential on the registration yourself, then call WithFederatedManagedIdentityCredential with the identity’s client ID. For the values to use, see Use a managed identity trust that you created.