[Identity] Documentation improvements (Azure#31798)

Added a disclaimer to the VisualStudioCodeCredential class docstring to highlight its shortcomings. Also slightly updated the EnvironmentCredential class docstring to include a missing envvar. Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com> Signed-off-by: Paul Van Eck <paulvaneck@microsoft.com>
azure-sdk · Oct 28, 2022 · 980f59e · 980f59e
1 parent 1019336
commit 980f59e
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 3 deletions.
diff --git a/sdk/identity/azure-identity/README.md b/sdk/identity/azure-identity/README.md
@@ -242,7 +242,7 @@ While the `DefaultAzureCredential` is generally the quickest way to get started
 
     ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
     AzureCliCredential cliCredential = new AzureCliCredentialBuilder().build();
-    
+
     ChainedTokenCredential credential = new ChainedTokenCredentialBuilder().addLast(managedIdentityCredential).addLast(cliCredential).build();
 
     // Azure SDK client builders accept the credential as a parameter
@@ -476,7 +476,7 @@ Credentials can be chained together to be tried in turn until one succeeds using
     </tr>
     <tr>
       <td><code>AZURE_CLIENT_CERTIFICATE_PATH</code></td>
-      <td>path to a PEM-encoded certificate file including private key</td>
+      <td>path to a PFX or PEM-encoded certificate file including private key</td>
     </tr>
     <tr>
         <td><code>AZURE_CLIENT_CERTIFICATE_PASSWORD</code></td>
@@ -500,6 +500,10 @@ Credentials can be chained together to be tried in turn until one succeeds using
       <td><code>AZURE_CLIENT_ID</code></td>
       <td>ID of an Azure AD application</td>
     </tr>
+    <tr>
+      <td><code>AZURE_TENANT_ID</code></td>
+      <td>(optional) ID of the application's Azure AD tenant</td>
+    </tr>
     <tr>
       <td><code>AZURE_USERNAME</code></td>
       <td>a username (usually an email address)</td>

diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/EnvironmentCredential.java
@@ -36,6 +36,7 @@
  *     <li>{@link Configuration#PROPERTY_AZURE_CLIENT_ID AZURE_CLIENT_ID}</li>
  *     <li>{@link Configuration#PROPERTY_AZURE_USERNAME AZURE_USERNAME}</li>
  *     <li>{@link Configuration#PROPERTY_AZURE_PASSWORD AZURE_PASSWORD}</li>
+ *     <li>{@link Configuration#PROPERTY_AZURE_TENANT_ID AZURE_TENANT_ID}</li>
  * </ul>
  */
 @Immutable

diff --git a/sdk/identity/azure-identity/src/main/java/com/azure/identity/VisualStudioCodeCredential.java b/sdk/identity/azure-identity/src/main/java/com/azure/identity/VisualStudioCodeCredential.java
@@ -21,7 +21,13 @@
 import java.util.concurrent.atomic.AtomicReference;
 
 /**
- * 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.
+ *
+ * <p>It's a <a href="https://github.com/Azure/azure-sdk-for-java/issues/27364">known issue</a> that this credential doesn't
+ * work with <a href="https://marketplace.visualstudio.com/items?itemName=ms-vscode.azure-account">Azure Account extension</a>
+ * versions newer than <strong>0.9.11</strong>. A long-term fix to this problem is in progress. In the meantime, consider
+ * authenticating with {@link AzureCliCredential}.</p>
  */
 public class VisualStudioCodeCredential implements TokenCredential {
     private final IdentityClient identityClient;