github/azure-sdk-for-cpp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add a readme section for user and system assigned managed identity for ManagedIdentityCredential. (#5838)

Browse Source 
* 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.
This commit is contained in:
Ahson Khan 2024-09-21 00:00:12 -07:00 committed by GitHub
parent b1f147e884
commit 309a390947
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 69 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
sdk/identity/azure-identity/README.md
View File

@ -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 = "<your managed identity client ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ClientId, userAssignedClientId);
auto credential = std::make_shared<ManagedIdentityCredential>(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 = "<your managed identity resource ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ResourceId, userAssignedResourceId);
auto credential = std::make_shared<ManagedIdentityCredential>(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 = "<your managed identity object ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ObjectId, userAssignedObjectId);
auto credential = std::make_shared<ManagedIdentityCredential>(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<ManagedIdentityCredential>(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<ManagedIdentityCredential>();
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/