Update readme for Identity (#2241)

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(<your project name> 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
+
+<table border="1" width="100%">
+  <thead>
+    <tr>
+      <th>credential class</th>
+      <th>usage</th>
+      <th>configuration</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>ClientSecretCredential</code></td>
+      <td>authenticates a service principal using a secret</td>
+      <td><a href="https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals">Service principal authentication</a></td>
+    </tr>
+  </tbody>
+</table>
+
+## Environment Variables
+`EnvironmentCredential` can be configured with environment variables.
+
+#### Service principal with secret
+<table border="1" width="100%">
+  <thead>
+    <tr>
+      <th>variable name</th>
+      <th>value</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>AZURE_CLIENT_ID</code></td>
+      <td>id of an Azure Active Directory application</td>
+    </tr>
+    <tr>
+      <td><code>AZURE_TENANT_ID</code></td>
+      <td>id of the application's Azure Active Directory tenant</td>
+    </tr>
+    <tr>
+      <td><code>AZURE_CLIENT_SECRET</code></td>
+      <td>one of the application's client secrets</td>
+    </tr>
+  </tbody>
+</table>
 
 ## 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.
 
 <!-- LINKS -->
+[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/