Updating Identity for 1.8.0 release (Azure#32353)

* [Identity] Update documentation (Azure#31867)

This updates the README and TROUBLESHOOTING files for
greater consistency with other language docs and for general
enhancement. Code snippets were added for the README.

Ref: Azure#31064

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>
Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>

* fix error messages with AADSTS and az login (Azure#31949)

* fix error messages with AADSTS and az login

* Update SharedTokenCacheCredential XML class documentation (Azure#32195)

* [Identity] Class documentation improvements (Azure#32043)

This adds additional details to the docstrings for
some of the credential classes. Users may find the
added info helpful.

Also added missing envvar in README.

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>

* Update Azure.Identity changelog (Azure#32216)

* Handle Managed Identity json parse errors as CredentialUnAvailableException (Azure#32272)

* handle json parse errors as CredentialNotAvailable

* update changelog for 1.8.0 release

* update csproj version

Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>
Co-authored-by: Paul Van Eck <paulvaneck@microsoft.com>
Co-authored-by: Scott Addie <10702007+scottaddie@users.noreply.github.com>
Co-authored-by: Christopher Scott <chriss@microsoft.com>

Author: 4 people

sdk/identity/Azure.Identity/CHANGELOG.md

@@ -1,14 +1,24 @@
 # Release History
 
-## 1.8.0-beta.2 (Unreleased)
+## 1.8.0 (2022-11-08)
 
-### Features Added
+### Bugs Fixed
+- Fixed error message parsing in `AzureCliCredential` which would misinterpret AAD errors with the need to login with `az login`. [#26894](https://github.com/Azure/azure-sdk-for-net/issues/26894), [#29109](https://github.com/Azure/azure-sdk-for-net/issues/29109)
+- `ManagedIdentityCredential` will no longer fail when a response received from the endpoint is invalid JSON. It now treats this scenario as if the credential is unavailable. [#30467](https://github.com/Azure/azure-sdk-for-net/issues/30467), [#32061](https://github.com/Azure/azure-sdk-for-net/issues/32061)
 
-### Breaking Changes
+## 1.9.0-beta.1 (2022-10-13)
 
-### Bugs Fixed
+### Features Added
+- Credentials that are implemented via launching a sub-process to acquire tokens now have configurable timeouts. This addresses scenarios where these proceses can take longer than the current default timeout values. (A community contribution, courtesy of _[reynaldoburgos](https://github.com/reynaldoburgos)_). The affected credentials and their associated options are:
+  - `AzureCliCredential` and `AzureCliCredentialOptions.CliProcessTimeout`
+  - `AzurePowerShellCredential` and `AzurePowerShellCredentialOptions.PowerShellProcessTimeout`
+  - `VisualStudioCredential` and `VisualStudioCredentialOptions.VisualStudioProcessTimeout`
+  - `DefaultAzureCredential` and `DefaultAzureCredentialOptions.DeveloperCredentialTimeout`  Note: this option applies to all developer credentials above when using `DefaultAzureCredential`.
 
-### Other Changes
+### Acknowledgments
+Thank you to our developer community members who helped to make Azure Identity better with their contributions to this release:
+
+- _[reynaldoburgos](https://github.com/reynaldoburgos)_
 
 ## 1.8.0-beta.1 (2022-10-13)
 
@@ -104,7 +114,7 @@ Thank you to our developer community members who helped to make Azure Identity b
 ### Breaking Changes from 1.5.0-beta.4
 - The `AllowMultiTenantAuthentication` option has been removed and the default behavior is now as if it were true. The multi-tenant discovery feature can be totally disabled by either setting an `AppContext` switch named "Azure.Identity.DisableTenantDiscovery" to `true` or by setting the environment variable "AZURE_IDENTITY_DISABLE_MULTITENANTAUTH" to "true".
 - Removed the `IsPIILoggingEnabled` property from `TokenCredentialOptions`, similar functionality is planned to be added to `TokenCredentialOptions.Diagnostics` in a later release.
-- Removed `RegionalAuthority` from `ClientCertificateCredentialOptions` and `ClientSecretCredentialOptions`, along with the `RegionalAuthority` type. This feature will stay in preview, and these APIs will be added back in `1.6.0-beta.1`.
+- Removed `RegionalAuthority` from `ClientCertificateCredentialOptions` and `ClientSecretCredentialOptions`, along with the `RegionalAuthority` type.
 - Renamed struct `TokenCacheDetails` to `TokenCacheData`.
 - Renamed class `TokenCacheNotificationDetails` to `TokenCacheRefreshArgs`.
 - Updated `CacheBytes` property on `TokenCacheData` to be readonly and a required constructor parameter.

sdk/identity/Azure.Identity/README.md

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <Description>This is the implementation of the Azure SDK Client Library for Azure Identity</Description>
     <AssemblyTitle>Microsoft Azure.Identity Component</AssemblyTitle>
-    <Version>1.8.0-beta.2</Version>
+    <Version>1.8.0</Version>
     <!--The ApiCompatVersion is managed automatically and should not generally be modified manually.-->
     <ApiCompatVersion>1.7.0</ApiCompatVersion>
     <PackageTags>Microsoft Azure Identity;$(PackageCommonTags)</PackageTags>

sdk/identity/Azure.Identity/TROUBLESHOOTING.md

@@ -6,10 +6,10 @@
 using System.Globalization;
 using System.IO;
 using System.Runtime.InteropServices;
-using System.Threading;
-using System.Threading.Tasks;
 using System.Text.Json;
 using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
 using Azure.Core;
 using Azure.Core.Pipeline;
 using Azure.Identitiy;
@@ -29,7 +29,7 @@ public class AzureCliCredential : TokenCredential
         internal const string Troubleshoot = "See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/azclicredential/troubleshoot";
         internal const string InteractiveLoginRequired = "Azure CLI could not login. Interactive login is required.";
         internal const string CLIInternalError = "CLIInternalError: The command failed with an unexpected error. Here is the traceback:";
-        internal TimeSpan CliProcessTimeout { get; private set;}
+        internal TimeSpan CliProcessTimeout { get; private set; }
 
         // The default install paths are used to find Azure CLI if no path is specified. This is to prevent executing out of the current working directory.
         private static readonly string DefaultPathWindows = $"{EnvironmentVariables.ProgramFilesX86}\\Microsoft SDKs\\Azure\\CLI2\\wbin;{EnvironmentVariables.ProgramFiles}\\Microsoft SDKs\\Azure\\CLI2\\wbin";
@@ -146,10 +146,11 @@ private async ValueTask<AccessToken> RequestCliAccessTokenAsync(bool async, Toke
                     throw new CredentialUnavailableException(AzureCLINotInstalled);
                 }
 
+                bool isAADSTSError = exception.Message.Contains("AADSTS");
                 bool isLoginError = exception.Message.IndexOf("az login", StringComparison.OrdinalIgnoreCase) != -1 ||
                                     exception.Message.IndexOf("az account set", StringComparison.OrdinalIgnoreCase) != -1;
 
-                if (isLoginError)
+                if (isLoginError && !isAADSTSError)
                 {
                     throw new CredentialUnavailableException(AzNotLogIn);
                 }

sdk/identity/Azure.Identity/src/Azure.Identity.csproj

@@ -13,18 +13,39 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using client secret, or username and password,
-    /// details configured in the following environment variables:
+    /// Enables authentication to Azure Active Directory using a client secret or certificate, or as a user
+    /// with a username and password.
+    /// <para>
+    /// Configuration is attempted in this order, using these environment variables:
+    /// </para>
+    ///
+    /// <b>Service principal with secret:</b>
     /// <list type="table">
     /// <listheader><term>Variable</term><description>Description</description></listheader>
-    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant(directory) ID.</description></item>
-    /// <item><term>AZURE_CLIENT_ID</term><description>The client(application) ID of an App Registration in the tenant.</description></item>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_CLIENT_SECRET</term><description>A client secret that was generated for the App Registration.</description></item>
+    /// </list>
+    ///
+    /// <b>Service principal with certificate:</b>
+    /// <list type="table">
+    /// <listheader><term>Variable</term><description>Description</description></listheader>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_CLIENT_CERTIFICATE_PATH</term><description>A path to certificate and private key pair in PEM or PFX format, which can authenticate the App Registration.</description></item>
-    /// <item><term>AZURE_CLIENT_SEND_CERTIFICATE_CHAIN</term><description>Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true` or `1`, authentication requests include the x5c header.</description></item>
+    /// <item><term>AZURE_CLIENT_CERTIFICATE_PASSWORD</term><description>(Optional) The password protecting the certificate file (currently only supported for PFX (PKCS12) certificates).</description></item>
+    /// <item><term>AZURE_CLIENT_SEND_CERTIFICATE_CHAIN</term><description>(Optional) Specifies whether an authentication request will include an x5c header to support subject name / issuer based authentication. When set to `true` or `1`, authentication requests include the x5c header.</description></item>
+    /// </list>
+    ///
+    /// <b>Username and password:</b>
+    /// <list type="table">
+    /// <listheader><term>Variable</term><description>Description</description></listheader>
+    /// <item><term>AZURE_TENANT_ID</term><description>The Azure Active Directory tenant (directory) ID.</description></item>
+    /// <item><term>AZURE_CLIENT_ID</term><description>The client (application) ID of an App Registration in the tenant.</description></item>
     /// <item><term>AZURE_USERNAME</term><description>The username, also known as upn, of an Azure Active Directory user account.</description></item>
     /// <item><term>AZURE_PASSWORD</term><description>The password of the Azure Active Directory user account. Note this does not support accounts with MFA enabled.</description></item>
     /// </list>
+    ///
     /// This credential ultimately uses a <see cref="ClientSecretCredential"/>, <see cref="ClientCertificateCredential"/>, or <see cref="UsernamePasswordCredential"/> to
     /// perform the authentication using these details. Please consult the
     /// documentation of that class for more details.

sdk/identity/Azure.Identity/src/Credentials/AzureCliCredential.cs

@@ -15,7 +15,8 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Authenticates using tokens in the local cache shared between Microsoft applications.
+    /// Authenticates using tokens in a local cache file. This is a legacy mechanism for authenticating clients using credentials provided to Visual Studio.
+    /// This mechanism for Visual Studio authentication has been replaced by the <see cref="VisualStudioCredential"/>.
     /// </summary>
     public class SharedTokenCacheCredential : TokenCredential
     {

sdk/identity/Azure.Identity/src/Credentials/EnvironmentCredential.cs

@@ -15,7 +15,13 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using data from Visual Studio Code.
+    /// Enables authentication to Azure Active Directory as the user signed in to Visual Studio Code via
+    /// the 'Azure Account' extension.
+    ///
+    /// It's a <see href="https://github.com/Azure/azure-sdk-for-net/issues/27263">known issue</see> that `VisualStudioCodeCredential`
+    /// doesn't work with <see href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account">Azure Account extension</see>
+    /// versions newer than <b>0.9.11</b>. A long-term fix to this problem is in progress. In the meantime, consider authenticating
+    /// with <see cref="AzureCliCredential"/>.
     /// </summary>
     public class VisualStudioCodeCredential : TokenCredential
     {

sdk/identity/Azure.Identity/src/Credentials/SharedTokenCacheCredential.cs

@@ -18,7 +18,9 @@
 namespace Azure.Identity
 {
     /// <summary>
-    /// Enables authentication to Azure Active Directory using data from Visual Studio
+    /// Enables authentication to Azure Active Directory using data from Visual Studio 2017 or later. See
+    /// <seealso href="https://learn.microsoft.com/dotnet/azure/configure-visual-studio" /> for more information
+    /// on how to configure Visual Studio for Azure development.
     /// </summary>
     public class VisualStudioCredential : TokenCredential
     {

sdk/identity/Azure.Identity/src/Credentials/VisualStudioCodeCredential.cs

@@ -61,6 +61,10 @@ protected virtual async ValueTask<AccessToken> HandleResponseAsync(
 
                 message = GetMessageFromResponse(json.RootElement);
             }
+            catch (JsonException jex)
+            {
+                throw new CredentialUnavailableException(UnexpectedResponse, jex);
+            }
             catch (Exception e)
             {
                 exception = e;