Existing Entra ID registrations
Ce contenu n’est pas encore disponible dans votre langue.
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.
Reference an existing registration
Section titled “Reference an existing registration”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.
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();var builder = DistributedApplication.CreateBuilder(args);
var tenantId = builder.AddParameter("entra-tenant-id");var apiClientId = builder.AddParameter("entra-api-client-id");
var entraApi = builder.AddExistingEntraIdApplication("entra-api", tenantId, apiClientId);
builder.AddDotnetProject("api", "../Api/Api.csproj") .WithReference(entraApi);
// After adding all resources, run the app...builder.Build().Run();Each ID accepts a literal value or a parameter. In TypeScript, you can mix them:
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" });var clientSecret = builder.AddParameter("entra-secret", secret: true);
var entraApi = builder.AddExistingEntraIdApplication( "entra-api", tenantId: "aaaabbbb-0000-cccc-1111-dddd2222eeee", clientId: "00001111-aaaa-2222-bbbb-3333cccc4444") .WithClientSecret(clientSecret);
builder.AddExecutable("worker", "node", ".", "worker.mjs") .WithReference(entraApi, connectionName: "AUTH");In C#, the overloads take two literals or two parameters.
Validation
Section titled “Validation”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.
Choose how to reference the registration
Section titled “Choose how to reference the registration”You can also convert an AddEntraIdApplication resource with AsExistingApplication. The two approaches differ in the Azure setup that they keep.
| Approach | Azure provisioning | Use it when |
|---|---|---|
AddExistingEntraIdApplication | Not enabled | The AppHost needs only the registration’s settings. It needs no Azure or Microsoft Graph access. |
AddEntraIdApplication(...).AsExistingApplication(...) | Kept | You 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.
const entraApi = await builder.addEntraIdApplication("entra-api") .asExistingApplication(tenantId, apiClientId);var entraApi = builder.AddEntraIdApplication("entra-api") .AsExistingApplication(tenantId: tenantId, clientId: 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.
Know which settings still apply
Section titled “Know which settings still apply”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.
| Setting | Existing registration |
|---|---|
WithClientSecret, WithClientCapability, WithSendX5C, and the certificate and signed assertion credentials | Supported. The registration must already trust the credential. |
WithFederatedManagedIdentityCredential | Supported. Configure the trust yourself first. |
WithAudience, WithSignInAudience, WithInstance | Supported. They affect only the referencing app’s configuration. |
WithApplicationIdUri with a URI, and WithScope | Supported. They describe an existing API. |
WithApiPermissions | Supported. It only produces the DownstreamApis configuration. |
WithRedirectUris, WithIdTokenIssuance | Throws. Configure these in the registration’s Authentication settings. |
WithOwners, WithApplicationOwners, WithServicePrincipalOwners | Throws. |
WithAppRole, PublishWithAppRoleAssignment | Throws. |
WithAdminConsent and WithPreAuthorizedApplication | Throws. For Microsoft Graph and other external APIs, this includes the withExternalApiAdminConsent method in TypeScript. |
WithApplicationIdUri without a URI | Throws. Aspire can’t infer an existing API’s URI. |
RunWithLocalDeveloperCertificateCredential, PublishWithFederatedManagedIdentityCredential | Throws. 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.
Describe an existing API
Section titled “Describe an existing API”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.
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"]);var entraApi = builder.AddExistingEntraIdApplication("entra-api", tenantId, apiClientId) .WithApplicationIdUri("api://contoso-orders") .WithScope("Weather.Read", "Allows the app to read weather forecasts.", scope => { scope.Id = new Guid("5d1f7b84-3c2e-4a6e-9a1d-0b8f2c3d4e5f"); });
// entraWeb is a created registration, as in the expose and call APIs article.entraWeb.WithApiPermissions(entraApi, "Weather.Read");GetScopeUri requires an application ID URI.
Existing registrations as callers
Section titled “Existing registrations as callers”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.