Aspirerelease/17.0

Entra ID lifecycle and permissions

Цей контент ще не доступний вашою мовою.

Microsoft Entra ID registrations live in your tenant’s directory, not in an Azure resource group. This affects which permissions you need, how deployments update registrations, and what remains after you delete your Azure resources. This article applies only to registrations that Aspire creates, because Aspire never changes existing registrations.

The identity that provisions your Azure resources also creates the registrations. Features that change more of the tenant need more privileges.

FeatureWhat the deploying identity needs
Create registrations and service principalsPermission to deploy to the resource group, and permission to create application registrations and service principals in the subscription’s tenant. Tenant policy can restrict creation.
WithOwners, WithApplicationOwners, WithServicePrincipalOwnersApplication.ReadWrite.All, or a directory role that can manage owners.
RunWithLocalDeveloperCertificateCredentialApplication.ReadWrite.All for delegated access. An application identity can use Application.ReadWrite.OwnedBy for registrations that it owns.
WithAdminConsent for delegated permissionsA directory role such as Privileged Role Administrator, Cloud Application Administrator, or Application Administrator, or the DelegatedPermissionGrant.ReadWrite.All Graph permission.
WithAdminConsent for Microsoft Graph application permissionsPrivileged Role Administrator or a custom role, or the AppRoleAssignment.ReadWrite.All Graph permission when deploying as an application.
PublishWithAppRoleAssignmentAppRoleAssignment.ReadWrite.All and Application.Read.All with administrator consent. Delegated deployments also need a supported directory role. An Azure subscription Owner or Contributor role alone isn’t enough.

When WithCertificateFromKeyVault references a Key Vault resource in the AppHost, Aspire also assigns the Key Vault Certificate User role on that vault. Your developer identity receives it when you run, and referencing apps receive it when you publish. The role applies to the whole vault. For more information, see Role assignments for certificate access.

Aspire never grants more than the deploying identity is allowed to grant. However, a privileged identity applies whatever the AppHost declares. When you deploy from CI, use a dedicated identity with only the permissions that the features you use need, and review changes to consent, owners, and app role assignments in the AppHost as privileged changes.

Your apps don’t need these Graph permissions. Without consent calls, WithApiPermissions only lists permissions, so it needs nothing beyond creating the registration.

To avoid these requirements, reference an existing registration, which needs no Azure or Microsoft Graph access.

Aspire provisions registrations in two situations.

  • When you run the AppHost, Aspire creates the registration the first time it starts and reuses the deployment state on unchanged restarts. Configure local Azure provisioning first, with your subscription and location, and sign in to the Azure CLI.
  • When you publish or deploy, the registration is part of the generated deployment, for example with aspire deploy.

Registrations are always created in the subscription’s tenant, which isn’t necessarily your account’s home tenant.

Each registration has a display name and a directory-wide uniqueName. Both default to the resource name that you pass to AddEntraIdApplication, followed by the optional tenant-scoped suffix. Deployments with the same tenant, resource name, and suffix update the same registration, regardless of the resource group.

Each deployment replaces the registration’s application roles, scopes, and pre-authorized clients with the ones that the AppHost declares. For what that removes, see Understand how deployments update roles and Retire scopes and understand what deployments remove.

Separate registrations with a tenant-scoped suffix

Section titled “Separate registrations with a tenant-scoped suffix”

Different resource groups don’t isolate registrations in the same tenant. If two developers or two AppHosts use the same name and suffix, they update the same registration and overwrite each other’s settings. Use a tenant-scoped suffix to separate them. With the suffix dev-a, the resource entra-web creates entra-web-dev-a. The Aspire resource name and the environment variable names that apps receive don’t change.

  • When you run the AppHost, enter the suffix in the Tenant-scoped resource suffix field of the Azure provisioning dialog, or set the Azure:TenantResourceSuffix configuration key. Change or clear it with Change Azure context in the dashboard.
  • Interactive aspire deploy prompts for a suffix when Azure:TenantResourceSuffix isn’t configured. Set the key, even to an empty string, to skip the prompt. Non-interactive deployments use no suffix unless you configure one.
  • Published Azure templates expose a tenantResourceSuffix parameter that defaults to an empty string, so your local suffix isn’t embedded.

To set the suffix for one registration in published templates, use WithParameter:

apphost.mts
const entraApi = await builder.addEntraIdApplication("entra-api")
.withParameter("tenantResourceSuffix", { value: "production" });

Changing the name or the suffix targets a different registration and leaves the previous application and service principal in place. To keep using a registration that has a different uniqueName, reference it with AddExistingEntraIdApplication, or clean it up.

Use separate registrations for development and production, especially with the local developer certificate.

By default, Aspire assigns no owners, so Microsoft Entra’s default ownership behavior applies. To opt in, pass directory object IDs for users or service principals, as literals or parameters. WithOwners sets the owners of both the application and the service principal. Use WithApplicationOwners and WithServicePrincipalOwners to set them independently.

apphost.mts
const ownerId = await builder.addParameter("entra-owner-id");
const entraWeb = await builder.addEntraIdApplication("entra-web")
.withOwners(ownerId);

Aspire adds owners and never removes them. Grant ownership deliberately, because owners can manage the registration. WithOwners throws for an existing registration.

Removing a call from your AppHost doesn’t always remove what it created in the tenant.

ConfigurationAfter you remove it from the AppHost
Delegated consent from WithAdminConsentStays when no call remains for that client and API. Removing one scope from a remaining call revokes that scope.
Application permission consentStays. Remove the app role assignment in the Microsoft Entra admin center.
PublishWithAppRoleAssignmentStays. Remove the assignment in the Microsoft Entra admin center or with Microsoft Graph.
WithPreAuthorizedApplicationRevoked when you remove the last call and the registration still declares an API. Stays when the registration no longer declares an API.
Scopes and application ID URIsStay when the registration no longer declares an API.
OwnersStay.
Local developer certificatePublishing doesn’t revoke a key that an earlier run registered.

Removal never revokes tokens that were already issued. Tokens stay valid until they expire.

To remove access that Aspire no longer manages, use the Microsoft Entra admin center or Microsoft Graph. With the Azure CLI, use the client’s application ID to list delegated grants. For app role assignments, use the object ID of the service principal that received the assignment. For PublishWithAppRoleAssignment, use the caller managed identity’s principal ID, not the API’s servicePrincipalId deployment output. For a client’s application permissions, use the client’s service principal ID.

Terminal
# List and delete delegated permission grants of a client.
az ad app permission list-grants --id <client-app-id>
az rest --method DELETE --url "https://graph.microsoft.com/v1.0/oauth2PermissionGrants/<grant-id>"
# List and delete app role assignments for the principal you are cleaning up.
az rest --method GET --url "https://graph.microsoft.com/v1.0/servicePrincipals/<principal-object-id>/appRoleAssignments"
az rest --method DELETE --url "https://graph.microsoft.com/v1.0/servicePrincipals/<principal-object-id>/appRoleAssignments/<assignment-id>"
# List and delete certificate credentials, such as a local developer certificate.
az ad app credential list --id <app-id> --cert
az ad app credential delete --id <app-id> --key-id <key-id> --cert

The identity that runs these commands needs the same kind of privileges as the identity that granted the access.

Registrations aren’t deleted when you delete the resource group or stop the AppHost. Delete Azure resources deletes the resource group and then lists the registrations and service principals that remain, with their object IDs and tenant ID, so you can delete them yourself in the Microsoft Entra admin center or with Microsoft Graph.

To find a registration later, use the objectId, servicePrincipalId, and uniqueName deployment outputs. Delete only the registrations and service principals that belong to your application.

Deleted applications stay soft-deleted for 30 days. Restore or permanently delete the application before you redeploy with the same uniqueName.

ErrorLikely cause
Missing subscription configuration on the registrationAzure provisioning isn’t configured. Set the subscription, resource group, and location, or switch to an existing registration.
Creation fails with permission deniedCheck the Azure deployment permissions and the permission to create registrations in the tenant. For consent and role assignments, see Required permissions.
Creation fails because uniqueName already existsRestore or permanently delete the soft-deleted application, or choose a different name or suffix.
Authorization_RequestDenied on the service principal, Request_ResourceNotFound on a federated credential, or InvalidIdentifierUri on a new applicationMicrosoft Graph sometimes can’t find a newly created application yet. Deploy again. If the error persists, treat it as a real permissions problem.
CannotDeleteOrUpdateEnabledEntitlementThe deployment omitted an enabled application role. Keep it declared, and retire it in two deployments. Microsoft Graph also rejects removing an enabled scope.
AADSTS50011The redirect URI doesn’t match. Compare the URIs on the registration with the callback of the app that you opened.
AADSTS700054, or response_type 'id_token' is not enabledCall WithIdTokenIssuance, or enable ID tokens (used for implicit and hybrid flows) in the Authentication settings of an existing registration.
AADSTS700213The registration has no federated credential that matches the managed identity. Check the issuer, subject, and audience.
AADSTS28000A token request mixed scopes of more than one API. Request each API’s scopes separately.
Need admin approvalThe tenant restricts user consent. Ask an administrator to approve sign-in, or use WithAdminConsent with the privileges that it needs.
  • Aspire doesn’t assign application roles to users, groups, or applications. That includes granting a client an app role that an API in your AppHost declares with WithAppRole.
  • Aspire can’t delete the last application role. Keep it declared with isEnabled set to false, or delete it in the Microsoft Entra admin center.
  • Aspire doesn’t create, store, or rotate client secrets or certificates, except for the local developer certificate.
  • Aspire never modifies existing registrations.
  • The integration doesn’t install authentication middleware or protect routes in your apps.