From d73593827f364fc700fcf676600ee1fd52955558 Mon Sep 17 00:00:00 2001 From: Anton Kolesnyk <41349689+antkmsft@users.noreply.github.com> Date: Mon, 10 May 2021 18:31:12 +0000 Subject: [PATCH] Update readme for Identity (#2241) --- sdk/identity/azure-identity/README.md | 102 +++++++++++++++++++------- 1 file changed, 76 insertions(+), 26 deletions(-) diff --git a/sdk/identity/azure-identity/README.md b/sdk/identity/azure-identity/README.md index c70fb84ef..178e7fc19 100644 --- a/sdk/identity/azure-identity/README.md +++ b/sdk/identity/azure-identity/README.md @@ -1,30 +1,83 @@ -# Azure SDK Identity Library for C++ +# Azure Identity client library for C++ +The Azure Identity library provides Azure Active Directory token authentication support across the Azure SDK. It provides a set of `TokenCredential` implementations which can be used to construct Azure SDK clients which support AAD token authentication. +This library follows the [Azure SDK Design Guidelines for C++][azure_sdk_cpp_development_guidelines]. -Azure::Identity (`azure-identity`) provides shared primitives, abstractions, and helpers for modern Azure SDK client libraries written in the C++. These libraries follow the [Azure SDK Design Guidelines for C++][azure_sdk_cpp_development_guidelines]. - -The library contains commonly (but not universally) used credential types. + [Source code][source] | [API reference documentation][doxygen] | [Azure Active Directory documentation][aad_doc] ## Getting started +### Include the package -Typically, you will not need to download `azure-identity`; it will be downloaded for you as a dependency of the client libraries. In case you want to download it explicitly (to implement your own client library, for example), you can find the source -in here. +The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding [Azure SDK for C++ readme section][azsdk_vcpkg_install]. + +To install Azure Identity package via vcpkg: + +```cmd +> vcpkg install azure-identity-cpp +``` + +Then, use in your CMake file: + +```CMake +find_package(azure-identity-cpp CONFIG REQUIRED) +target_link_libraries( PRIVATE Azure::azure-identity) +``` ## Key concepts +### Credentials -Azure::Identity credentials: -- Client Secret Credential (`ClientSecretCredential`) -- Environment Credential (`EnvironmentCredential`) +A credential is a class which contains or can obtain the data needed for a service client to authenticate requests. Service clients across Azure SDK accept credentials when they are constructed, and service clients use those credentials to authenticate requests to the service. + +The Azure Identity library focuses on OAuth authentication with Azure Active directory, and it offers a variety of credential classes capable of acquiring an AAD token to authenticate service requests. All of the credential classes in this library are implementations of the `TokenCredential` abstract class in [azure-core][azure_core_library], and any of them can be used by to construct service clients capable of authenticating with a `TokenCredential`. + +### Authenticating Service Principals + + + + + + + + + + + + + + + + +
credential classusageconfiguration
ClientSecretCredentialauthenticates a service principal using a secretService principal authentication
+ +## Environment Variables +`EnvironmentCredential` can be configured with environment variables. + +#### Service principal with secret + + + + + + + + + + + + + + + + + + + + + +
variable namevalue
AZURE_CLIENT_IDid of an Azure Active Directory application
AZURE_TENANT_IDid of the application's Azure Active Directory tenant
AZURE_CLIENT_SECRETone of the application's client secrets
## Troubleshooting - -Three main ways of troubleshooting failures are: -- Inspecting exceptions -- Enabling logging (`Available in future release`) -- Distributed tracing (`Available in future release`) - -## Next steps - -Explore and install available Azure SDK libraries. +Credentials raise exceptions either when they fail to authenticate or cannot execute authentication. +When credentials fail to authenticate, the `AuthenticationException` is thrown and it has the `what()` functions returning the description why authentication failed. ## Contributing For details on contributing to this repository, see the [contributing guide][azure_sdk_for_cpp_contributing]. @@ -59,15 +112,12 @@ Security issues and bugs should be reported privately, via email, to the Microso Azure SDK for C++ is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-cpp/blob/master/sdk/core/azure-core/LICENSE) license. +[azsdk_vcpkg_install]: https://github.com/Azure/azure-sdk-for-cpp#download--install-the-sdk [azure_sdk_for_cpp_contributing]: https://github.com/Azure/azure-sdk-for-cpp/blob/master/CONTRIBUTING.md [azure_sdk_for_cpp_contributing_developer_guide]: https://github.com/Azure/azure-sdk-for-cpp/blob/master/CONTRIBUTING.md#developer-guide [azure_sdk_for_cpp_contributing_pull_requests]: https://github.com/Azure/azure-sdk-for-cpp/blob/master/CONTRIBUTING.md#pull-requests [azure_sdk_cpp_development_guidelines]: https://azure.github.io/azure-sdk/cpp_introduction.html -[azure_cli]: https://docs.microsoft.com/cli/azure -[azure_pattern_circuit_breaker]: https://docs.microsoft.com/azure/architecture/patterns/circuit-breaker -[azure_pattern_retry]: https://docs.microsoft.com/azure/architecture/patterns/retry -[azure_portal]: https://portal.azure.com -[azure_sub]: https://azure.microsoft.com/free/ -[c_compiler]: https://visualstudio.microsoft.com/vs/features/cplusplus/ -[cloud_shell]: https://docs.microsoft.com/azure/cloud-shell/overview -[cloud_shell_bash]: https://shell.azure.com/bash +[source]: https://github.com/Azure/azure-sdk-for-cpp/tree/master/sdk/identity/azure-identity +[aad_doc]: https://docs.microsoft.com/azure/active-directory/ +[azure_core_library]: https://github.com/Azure/azure-sdk-for-cpp/tree/master/sdk/core +[doxygen]: https://azure.github.io/azure-sdk-for-cpp/