[Identity] Add known issues section to readme (Azure#21222)

Author: mccoyp

sdk/identity/azure-identity/README.md

@@ -29,14 +29,14 @@ pip install azure-identity
 - Python 2.7 or a recent version of Python 3 (this library doesn't support
   end-of-life versions)
 
-### Authenticating during local development
+### Authenticate during local development
 
 When debugging and executing code locally it is typical for developers to use
 their own accounts for authenticating calls to Azure services. The Azure
 Identity library supports authenticating through developer tools to simplify
 local development.
 
-#### Authenticating via Visual Studio Code
+#### Authenticate via Visual Studio Code
 
 `DefaultAzureCredential` and `VisualStudioCodeCredential` can authenticate as
 the user signed in to Visual Studio Code's
@@ -45,7 +45,7 @@ After installing the extension, sign in to Azure in Visual Studio Code by
 pressing `F1` to open the command palette and running the `Azure: Sign In`
 command.
 
-#### Authenticating via the Azure CLI
+#### Authenticate via the Azure CLI
 
 `DefaultAzureCredential` and `AzureCliCredential` can authenticate as the user
 signed in to the [Azure CLI][azure_cli]. To sign in to the Azure CLI, run
@@ -66,7 +66,8 @@ to authenticate requests.
 
 The Azure Identity library focuses on OAuth authentication with Azure Active
 Directory (AAD). It offers a variety of credential classes capable of acquiring
-an AAD access token. See [Credential Classes](#credential-classes "Credential Classes") below for a list of this library's credential classes.
+an AAD access token. See the [Credential classes](#credential-classes "Credential classes") section below for a list of
+this library's credential classes.
 
 ### DefaultAzureCredential
 
@@ -111,11 +112,11 @@ in any hosting environment which supports managed identities, such as (this list
 
 The following examples are provided below:
 
-- [Authenticating with DefaultAzureCredential](#authenticating-with-defaultazurecredential "Authenticating with DefaultAzureCredential")
-- [Defining a custom authentication flow with ChainedTokenCredential](#defining-a-custom-authentication-flow-with-chainedtokencredential "Defining a custom authentication flow with ChainedTokenCredential")
+- [Authenticate with DefaultAzureCredential](#authenticate-with-defaultazurecredential "Authenticate with DefaultAzureCredential")
+- [Define a custom authentication flow with ChainedTokenCredential](#define-a-custom-authentication-flow-with-chainedtokencredential "Define a custom authentication flow with ChainedTokenCredential")
 - [Async credentials](#async-credentials "Async credentials")
 
-### Authenticating with `DefaultAzureCredential`
+### Authenticate with `DefaultAzureCredential`
 
 More details on configuring your environment to use the `DefaultAzureCredential`
 can be found in the class's [reference documentation][default_cred_ref].
@@ -133,7 +134,7 @@ default_credential = DefaultAzureCredential()
 client = BlobServiceClient(account_url, credential=default_credential)
 ```
 
-#### Enabling interactive authentication with `DefaultAzureCredential`
+#### Enable interactive authentication with `DefaultAzureCredential`
 
 Interactive authentication is disabled in the `DefaultAzureCredential` by
 default and can be enabled with a keyword argument:
@@ -146,7 +147,7 @@ When enabled, `DefaultAzureCredential` falls back to interactively
 authenticating via the system's default web browser when no other credential is
 available.
 
-#### Specifying a user assigned managed identity for `DefaultAzureCredential`
+#### Specify a user assigned managed identity for `DefaultAzureCredential`
 
 Many Azure hosts allow the assignment of a user assigned managed identity. To
 configure `DefaultAzureCredential` to authenticate a user assigned identity,
@@ -159,7 +160,7 @@ DefaultAzureCredential(managed_identity_client_id=client_id)
 Alternatively, set the environment variable `AZURE_CLIENT_ID` to the identity's
 client ID.
 
-### Defining a custom authentication flow with `ChainedTokenCredential`
+### Define a custom authentication flow with `ChainedTokenCredential`
 
 `DefaultAzureCredential` is generally the quickest way to get started developing
 applications for Azure. For more advanced scenarios,
@@ -221,7 +222,7 @@ default_credential = DefaultAzureCredential()
 client = SecretClient("https://my-vault.vault.azure.net", default_credential)
 ```
 
-## Cloud Configuration
+## Cloud configuration
 Credentials default to authenticating to the Azure Active Directory endpoint for
 Azure Public Cloud. To access resources in other clouds, such as Azure Government
 or a private cloud, configure credentials with the `authority` argument.
@@ -237,9 +238,9 @@ through a development tool, such as `AzureCliCredential`, use that tool's
 configuration. Similarly, `VisualStudioCodeCredential` accepts an `authority`
 argument but defaults to the authority matching VS Code's "Azure: Cloud" setting.
 
-## Credential Classes
+## Credential classes
 
-### Authenticating Azure Hosted Applications
+### Authenticate Azure hosted applications
 
 |credential|usage
 |-|-
@@ -248,29 +249,29 @@ argument but defaults to the authority matching VS Code's "Azure: Cloud" setting
 |[EnvironmentCredential][environment_cred_ref]|authenticate a service principal or user configured by environment variables
 |[ManagedIdentityCredential][managed_id_cred_ref]|authenticate the managed identity of an Azure resource
 
-### Authenticating Service Principals
+### Authenticate service principals
 
 |credential|usage
 |-|-
 |[ClientSecretCredential][client_secret_cred_ref]| authenticate a service principal using a secret
 |[CertificateCredential][cert_cred_ref]| authenticate a service principal using a certificate
 
-### Authenticating Users
+### Authenticate users
 
 |credential|usage
 |-|-
 |[InteractiveBrowserCredential][interactive_cred_ref]|interactively authenticate a user with the default web browser
 |[DeviceCodeCredential][device_code_cred_ref]| interactively authenticate a user on a device with limited UI
 |[UsernamePasswordCredential][userpass_cred_ref]| authenticate a user with a username and password (does not support multi-factor authentication)
 
-### Authenticating via Development Tools
+### Authenticate via development tools
 
 |credential|usage
 |-|-
 |[AzureCliCredential][cli_cred_ref]|authenticate as the user signed in to the Azure CLI
 |[VisualStudioCodeCredential][vscode_cred_ref]|authenticate as the user signed in to the Visual Studio Code Azure Account extension
 
-## Environment Variables
+## Environment variables
 
 [DefaultAzureCredential][default_cred_ref] and
 [EnvironmentCredential][environment_cred_ref] can be configured with
@@ -305,7 +306,7 @@ client secret and certificate are both present, the client secret will be used.
 
 See the [troubleshooting guide][troubleshooting_guide] for details on how to diagnose various failure scenarios.
 
-### Error Handling
+### Error handling
 
 Credentials raise `CredentialUnavailableError` when they're unable to attempt
 authentication because they lack required data or state. For example,
@@ -346,11 +347,13 @@ Client and management libraries listed on the
 which support Azure AD authentication accept credentials from this library. You can learn more
 about using these libraries in their documentation, which is linked from the release page.
 
-### B2C Support
+### Known issues
 
-This library does not support [Azure Active Directory B2C][b2c].
+This library doesn't support [Azure AD B2C][b2c].
 
-### Provide Feedback
+For other open issues, refer to the library's [GitHub repository](https://github.com/Azure/azure-sdk-for-python/issues?q=is%3Aopen+is%3Aissue+label%3AAzure.Identity).
+
+### Provide feedback
 
 If you encounter bugs or have suggestions, please
 [open an issue](https://github.com/Azure/azure-sdk-for-python/issues).