From 309a390947029c1751fe817e11a807ba8ff477cb Mon Sep 17 00:00:00 2001 From: Ahson Khan Date: Sat, 21 Sep 2024 00:00:12 -0700 Subject: [PATCH] Add a readme section for user and system assigned managed identity for ManagedIdentityCredential. (#5838) * Add a readme section for user and system assigned managed identity for MICredential. * Update the README to reflect new API surface and add section about Object ID. * Mention object ID in the intro. * Reorder the list of IDs mentioned to match the section order. --- sdk/identity/azure-identity/README.md | 69 +++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/sdk/identity/azure-identity/README.md b/sdk/identity/azure-identity/README.md index 897e811c5..aebf9b838 100644 --- a/sdk/identity/azure-identity/README.md +++ b/sdk/identity/azure-identity/README.md @@ -96,6 +96,74 @@ The [Managed identity authentication](https://learn.microsoft.com/entra/identity * [Azure Arc](https://learn.microsoft.com/azure/azure-arc/servers/managed-identity-authentication) * [Azure Virtual Machines](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-use-vm-token) +### Specify a user-assigned managed identity with `ManagedIdentityCredential` + +Many Azure hosts allow the assignment of a user-assigned managed identity. The following examples demonstrate configuring `ManagedIdentityCredential` to authenticate a user-assigned managed identity when deployed to an Azure host. The sample code uses the credential to authenticate a `BlobClient` from the [Azure::Storage::Blobs][blobs_client_library] client library. It also demonstrates how you can specify a user-assigned managed identity either by a client ID, resource ID, or an object ID. + +#### Client ID + +To use a client ID, create a `ManagedIdentityId` with `ManagedIdentityIdKind::ClientId`, set that as the `IdentityId` in the `ManagedIdentityCredentialOptions`, and pass that to the `ManagedIdentityCredential` constructor. For example: + +```cpp +// When deployed to an Azure host, ManagedIdentityCredential will authenticate the specified user-assigned managed identity. + +std::string userAssignedClientId = ""; +ManagedIdentityCredentialOptions options; +options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ClientId, userAssignedClientId); + +auto credential = std::make_shared(options); + +std::string blobUrl = "https://myaccount.blob.core.windows.net/mycontainer/myblob"; +auto blobClient = BlobClient(blobUrl, credential); +``` + +#### Resource ID + +Similarly, to use a resource ID, create a `ManagedIdentityId` with `ManagedIdentityIdKind::ResourceId`, set that as the `IdentityId` in the `ManagedIdentityCredentialOptions`, and pass that to the `ManagedIdentityCredential` constructor. The resource ID takes the form `/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}`. Because resource IDs can be built by convention, they can be more convenient when there are a large number of user-assigned managed identities in your environment. For example: + +```cpp +std::string userAssignedResourceId = ""; +ManagedIdentityCredentialOptions options; +options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ResourceId, userAssignedResourceId); + +auto credential = std::make_shared(options); + +auto blobClient = BlobClient(blobUrl, credential); +``` + +#### Object ID + +Similarly, to use an object ID, create a `ManagedIdentityId` with `ManagedIdentityIdKind::ObjectId`, set that as the `IdentityId` in the `ManagedIdentityCredentialOptions`, and pass that to the `ManagedIdentityCredential` constructor. For example: + +```cpp +std::string userAssignedObjectId = ""; +ManagedIdentityCredentialOptions options; +options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ObjectId, userAssignedObjectId); + +auto credential = std::make_shared(options); + +auto blobClient = BlobClient(blobUrl, credential); +``` + +### Specify a system-assigned managed identity with `ManagedIdentityCredential` + +You can express your intent to use a system-assigned managed identity, explicitly, by creating a `ManagedIdentityId` with `ManagedIdentityIdKind::SystemAssigned` and an empty ID value, set that as the `IdentityId` in the `ManagedIdentityCredentialOptions`, and pass that to the `ManagedIdentityCredential` constructor. For example: + +```cpp +ManagedIdentityCredentialOptions options; +options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::SystemAssigned, {}); + +auto credential = std::make_shared(options); +auto blobClient = BlobClient(blobUrl, credential); +``` + +An alternative way to specify a system-assigned managed identity, implicitly, is by calling the default `ManagedIdentityCredential` constructor. For example: + +```cpp +auto credential = std::make_shared(); +auto blobClient = BlobClient(blobUrl, credential); +``` + ## Environment Variables `DefaultAzureCredential` and `EnvironmentCredential` can be configured with environment variables. Each type of authentication requires values for specific variables: @@ -198,6 +266,7 @@ Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk [azure_sdk_cpp_development_guidelines]: https://azure.github.io/azure-sdk/cpp_introduction.html [default_azure_credential_auth_flow]: https://github.com/Azure/azure-sdk-for-cpp/blob/main/sdk/identity/azure-identity/img/mermaidjs/DefaultAzureCredentialAuthFlow.svg [source]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/identity/azure-identity +[blobs_client_library]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/storage/azure-storage-blobs [meid_doc]: https://learn.microsoft.com/entra/identity/ [azure_core_library]: https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/core [doxygen]: https://azure.github.io/azure-sdk-for-cpp/