From 1f1a36af8abf9d24625798dde8e2e20bc5b5831a Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 8 May 2025 10:15:32 -0500 Subject: [PATCH 1/4] Initial draft of new user-assigned managed ids. --- docs/azure/user-assigned-managed-identity.md | 73 ++++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 75 insertions(+) create mode 100644 docs/azure/user-assigned-managed-identity.md diff --git a/docs/azure/user-assigned-managed-identity.md b/docs/azure/user-assigned-managed-identity.md new file mode 100644 index 0000000000..ca0ed8331f --- /dev/null +++ b/docs/azure/user-assigned-managed-identity.md @@ -0,0 +1,73 @@ +--- +title: User-assigned managed identities +description: Learn how to use user-assigned managed identities in your .NET Aspire applications to securely access Azure resources. +ms.date: 05/08/2025 +--- + +# User-assigned managed identities in .NET Aspire + +You can use user-assigned managed identities (UMIs) in your .NET Aspire applications to securely access Azure resources. A user-assigned managed identity is a standalone Azure resource that you can assign to one or more services. This gives you more control over identity management and resource access. + +## Add a user-assigned managed identity + +To create a new user-assigned managed identity, use the `AddAzureUserAssignedIdentity` API in your distributed application builder: + +````csharp +var builder = DistributedApplication.CreateBuilder(args); + +var sharedMi = builder.AddAzureUserAssignedIdentity("custom-umi"); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +The preceding code creates a new managed identity named "custom-umi" that you can use with other resources in your application. + +## Reference an existing managed identity + +If you already have a managed identity, you can reference it using the method. This is useful when you want to use an identity that was created outside of your .NET Aspire project. + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var miName = builder.AddParameter("miName"); +var miResourceGroup = builder.AddParameter("miResourceGroup"); + +var sharedMi = builder.AddAzureUserAssignedIdentity("custom-umi") + .PublishAsExisting(miName, miResourceGroup); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +In the preceding example, you use parameters to provide the name and resource group of the existing identity. This allows you to reference the managed identity without creating a new one. + +## Assign roles to managed identities + +You can grant Azure roles to your managed identity using the WithRoleAssignments API. This lets your identity access other Azure resources, such as Azure Key Vault. + +```csharp +var builder = DistributedApplication.CreateBuilder(args); + +var sharedMi = builder.AddAzureUserAssignedIdentity("custom-umi"); + +builder.AddAzureKeyVault("secrets") + .WithRoleAssignments(sharedMi, BuiltInRole.Reader); + +// After adding all resources, run the app... + +builder.Build().Run(); +``` + +In this example, you give the Reader role to the managed identity for the Key Vault resource. + +For more information about managed identities, see Azure managed identities overview. + +## See also + +- [Azure managed identities overview](/azure/active-directory/managed-identities-azure-resources/overview) +- [Azure Key Vault](/azure/key-vault/general/basic-concepts) +- [Manage Azure role assignments](role-assignments.md) +- [.NET Aspire Azure integrations overview](integrations-overview.md) diff --git a/docs/toc.yml b/docs/toc.yml index f34bc60ef3..5d616ecd51 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -155,6 +155,8 @@ items: href: azure/configure-aca-environments.md - name: Manage role assignments href: azure/role-assignments.md + - name: User-assigned managed identity + href: azure/user-assigned-managed-identity.md - name: Azure AI Search displayName: azure search,search,azure ai,cognitive search,cognitive services href: azureai/azureai-search-document-integration.md From 07b3c110051ffbf47f7bcca038f895e16166cf85 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 8 May 2025 10:29:32 -0500 Subject: [PATCH 2/4] Edit pass and TOC reposition. --- docs/azure/user-assigned-managed-identity.md | 6 ++---- docs/toc.yml | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/azure/user-assigned-managed-identity.md b/docs/azure/user-assigned-managed-identity.md index ca0ed8331f..05ae189397 100644 --- a/docs/azure/user-assigned-managed-identity.md +++ b/docs/azure/user-assigned-managed-identity.md @@ -6,7 +6,7 @@ ms.date: 05/08/2025 # User-assigned managed identities in .NET Aspire -You can use user-assigned managed identities (UMIs) in your .NET Aspire applications to securely access Azure resources. A user-assigned managed identity is a standalone Azure resource that you can assign to one or more services. This gives you more control over identity management and resource access. +In this article, you learn how to add or reference user-assigned managed identities. You can add user-assigned managed identities (UMIs) in your .NET Aspire applications to securely access Azure resources. A user-assigned managed identity is a standalone Azure resource that you can assign to one or more service resources. UMIs give you more control over identity management and resource access. ## Add a user-assigned managed identity @@ -61,9 +61,7 @@ builder.AddAzureKeyVault("secrets") builder.Build().Run(); ``` -In this example, you give the Reader role to the managed identity for the Key Vault resource. - -For more information about managed identities, see Azure managed identities overview. +In this example, you give the Reader role to the managed identity for the Key Vault resource. For more information about role assignments, see [Manage Azure role assignments](role-assignments.md). ## See also diff --git a/docs/toc.yml b/docs/toc.yml index 5d616ecd51..3aab0d3c3d 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -153,10 +153,10 @@ items: href: azure/local-provisioning.md - name: Configure Azure Container Apps environments href: azure/configure-aca-environments.md - - name: Manage role assignments - href: azure/role-assignments.md - name: User-assigned managed identity href: azure/user-assigned-managed-identity.md + - name: Manage role assignments + href: azure/role-assignments.md - name: Azure AI Search displayName: azure search,search,azure ai,cognitive search,cognitive services href: azureai/azureai-search-document-integration.md From 73fff67459d67a6009a5825292d6413be2fc6fa1 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 8 May 2025 10:44:03 -0500 Subject: [PATCH 3/4] Fix issue with backticks --- docs/azure/user-assigned-managed-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/user-assigned-managed-identity.md b/docs/azure/user-assigned-managed-identity.md index 05ae189397..03b90d848a 100644 --- a/docs/azure/user-assigned-managed-identity.md +++ b/docs/azure/user-assigned-managed-identity.md @@ -12,7 +12,7 @@ In this article, you learn how to add or reference user-assigned managed identit To create a new user-assigned managed identity, use the `AddAzureUserAssignedIdentity` API in your distributed application builder: -````csharp +```csharp var builder = DistributedApplication.CreateBuilder(args); var sharedMi = builder.AddAzureUserAssignedIdentity("custom-umi"); From 62bda17ebbae1853812b897d642200b3071f7734 Mon Sep 17 00:00:00 2001 From: David Pine Date: Thu, 8 May 2025 10:59:41 -0500 Subject: [PATCH 4/4] Minor updates --- docs/azure/user-assigned-managed-identity.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/user-assigned-managed-identity.md b/docs/azure/user-assigned-managed-identity.md index 03b90d848a..6874894698 100644 --- a/docs/azure/user-assigned-managed-identity.md +++ b/docs/azure/user-assigned-managed-identity.md @@ -6,7 +6,7 @@ ms.date: 05/08/2025 # User-assigned managed identities in .NET Aspire -In this article, you learn how to add or reference user-assigned managed identities. You can add user-assigned managed identities (UMIs) in your .NET Aspire applications to securely access Azure resources. A user-assigned managed identity is a standalone Azure resource that you can assign to one or more service resources. UMIs give you more control over identity management and resource access. +In this article, you learn how to add or reference user-assigned managed identities (UMIs). You can add UMIs in your .NET Aspire applications to securely access Azure resources. A UMI is a standalone Azure resource that you can assign to one or more service resources. UMIs give you more control over identity management and resource access. ## Add a user-assigned managed identity