[Identity] Fixes after manual tests (#18011)

* AzureCLI fix and better comments

* several improvements

sdk/identity/identity/CHANGELOG.md

@@ -13,6 +13,8 @@
 
 ### Bugs Fixed
 
+- Fixed a bug that caused `AzureCliCredential` to fail when a custom tenant ID was provided.
+
 ### Other Changes
 
 ## 2.0.0-beta.6 (2021-09-09)

sdk/identity/identity/src/credentials/applicationCredential.browser.ts

@@ -16,12 +16,17 @@ const logger = credentialLogger("ApplicationCredential");
  * Provides a default {@link ChainedTokenCredential} configuration for
  * applications that will be deployed to Azure.
  *
- * Only available in NodeJS.
+ * Only available in Node.js
  */
 export class ApplicationCredential extends ChainedTokenCredential {
   /**
    * Creates an instance of the ApplicationCredential class.
    *
+   * The ApplicationCredential provides a default {@link ChainedTokenCredential} configuration for
+   * applications that will be deployed to Azure.
+   *
+   * Only available in Node.js
+   *
    * @param options - Options for configuring the client which makes the authentication request.
    */
   constructor(_tokenCredentialOptions?: TokenCredentialOptions) {

sdk/identity/identity/src/credentials/applicationCredential.ts

@@ -39,20 +39,22 @@ export const ApplicationCredentials: ApplicationCredentialConstructor[] = [
 
 /**
  * Provides a default {@link ChainedTokenCredential} configuration that should
- * work for most applications that use the Azure SDK.  The following credential
- * types will be tried, in order:
- *
- * - {@link EnvironmentCredential}
- * - {@link ManagedIdentityCredential}
-
- *
- * Consult the documentation of these credential types for more information
- * on how they attempt authentication.
+ * work for most applications that use the Azure SDK.
  */
 export class ApplicationCredential extends ChainedTokenCredential {
   /**
    * Creates an instance of the ApplicationCredential class.
    *
+   * The ApplicationCredential provides a default {@link ChainedTokenCredential} configuration that should
+   * work for most applications that use the Azure SDK.  The following credential
+   * types will be tried, in order:
+   *
+   * - {@link EnvironmentCredential}
+   * - {@link ManagedIdentityCredential}
+   *
+   * Consult the documentation of these credential types for more information
+   * on how they attempt authentication.
+   *
    * @param options - Optional parameters. See {@link ApplicationCredentialOptions}.
    */
   constructor(options?: ApplicationCredentialOptions) {

sdk/identity/identity/src/credentials/authorizationCodeCredential.browser.ts

@@ -12,6 +12,9 @@ const BrowserNotSupportedError = new Error(
 const logger = credentialLogger("AuthorizationCodeCredential");
 
 export class AuthorizationCodeCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor(
     tenantId: string | "common",
     clientId: string,

sdk/identity/identity/src/credentials/azureCliCredential.browser.ts

@@ -8,7 +8,14 @@ import { credentialLogger, formatError } from "../util/logging";
 const BrowserNotSupportedError = new Error("AzureCliCredential is not supported in the browser.");
 const logger = credentialLogger("AzureCliCredential");
 
+/**
+ * This credential will use the currently logged-in user login information
+ * via the Azure CLI ('az') commandline tool.
+ */
 export class AzureCliCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/azureCliCredential.ts

@@ -7,7 +7,7 @@ import { createSpan } from "../util/tracing";
 import { CredentialUnavailableError } from "../client/errors";
 import { SpanStatusCode } from "@azure/core-tracing";
 import { credentialLogger, formatSuccess, formatError } from "../util/logging";
-import * as child_process from "child_process";
+import child_process from "child_process";
 import { ensureValidScope, getScopeResource } from "../util/scopeUtils";
 import { AzureCliCredentialOptions } from "./azureCliCredentialOptions";
 import { processMultiTenantRequest } from "../util/validateMultiTenant";
@@ -55,8 +55,8 @@ export const cliCredentialInternals = {
             "--output",
             "json",
             "--resource",
-            ...tenantSection,
-            resource
+            resource,
+            ...tenantSection
           ],
           { cwd: cliCredentialInternals.getSafeWorkingDir() },
           (error, stdout, stderr) => {
@@ -77,15 +77,16 @@ const logger = credentialLogger("AzureCliCredential");
  * via the Azure CLI ('az') commandline tool.
  * To do so, it will read the user access token and expire time
  * with Azure CLI command "az account get-access-token".
- * To be able to use this credential, ensure that you have already logged
- * in via the 'az' tool using the command "az login" from the commandline.
  */
 export class AzureCliCredential implements TokenCredential {
   private tenantId?: string;
 
   /**
    * Creates an instance of the {@link AzureCliCredential}.
    *
+   * To use this credential, ensure that you have already logged
+   * in via the 'az' tool using the command "az login" from the commandline.
+   *
    * @param options - Options, to optionally allow multi-tenant requests.
    */
   constructor(options?: AzureCliCredentialOptions) {

sdk/identity/identity/src/credentials/azurePowerShellCredential.browser.ts

@@ -12,9 +12,11 @@ const logger = credentialLogger("AzurePowerShellCredential");
 
 /**
  * This credential will use the currently-logged-in user's login information via the Azure Power Shell command line tool.
- * This credential is not supported in browsers.
  */
 export class AzurePowerShellCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/azurePowerShellCredential.ts

@@ -87,19 +87,19 @@ if (isWindows) {
  * This credential will use the currently logged-in user information from the
  * Azure PowerShell module. To do so, it will read the user access token and
  * expire time with Azure PowerShell command `Get-AzAccessToken -ResourceUrl {ResourceScope}`
- *
- * To be able to use this credential:
- * - Install the Azure Az PowerShell module with:
- *   `Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force`.
- * - You have already logged in to Azure PowerShell using the command
- * `Connect-AzAccount` from the command line.
  */
 export class AzurePowerShellCredential implements TokenCredential {
   private tenantId?: string;
 
   /**
    * Creates an instance of the {@link AzurePowershellCredential}.
    *
+   * To use this credential:
+   * - Install the Azure Az PowerShell module with:
+   *   `Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force`.
+   * - You have already logged in to Azure PowerShell using the command
+   * `Connect-AzAccount` from the command line.
+   *
    * @param options - Options, to optionally allow multi-tenant requests.
    */
   constructor(options?: AzurePowerShellCredentialOptions) {

sdk/identity/identity/src/credentials/clientCertificateCredential.browser.ts

@@ -9,7 +9,14 @@ const BrowserNotSupportedError = new Error(
 );
 const logger = credentialLogger("ClientCertificateCredential");
 
+/**
+ * Enables authentication to Azure Active Directory using a PEM-encoded
+ * certificate that is assigned to an App Registration.
+ */
 export class ClientCertificateCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/defaultAzureCredential.ts

@@ -67,22 +67,26 @@ export const defaultCredentials: DefaultCredentialConstructor[] = [
 
 /**
  * Provides a default {@link ChainedTokenCredential} configuration that should
- * work for most applications that use the Azure SDK.  The following credential
- * types will be tried, in order:
- *
- * - {@link EnvironmentCredential}
- * - {@link ManagedIdentityCredential}
- * - {@link VisualStudioCodeCredential}
- * - {@link AzureCliCredential}
- * - {@link AzurePowerShellCredential}
- *
- * Consult the documentation of these credential types for more information
- * on how they attempt authentication.
+ * work for most applications that use the Azure SDK.
  */
 export class DefaultAzureCredential extends ChainedTokenCredential {
   /**
    * Creates an instance of the DefaultAzureCredential class.
    *
+   * This credential provides a default {@link ChainedTokenCredential} configuration that should
+   * work for most applications that use the Azure SDK.
+   *
+   * The following credential types will be tried, in order:
+   *
+   * - {@link EnvironmentCredential}
+   * - {@link ManagedIdentityCredential}
+   * - {@link VisualStudioCodeCredential}
+   * - {@link AzureCliCredential}
+   * - {@link AzurePowerShellCredential}
+   *
+   * Consult the documentation of these credential types for more information
+   * on how they attempt authentication.
+   *
    * **Note**: `VisualStudioCodeCredential` is provided by a plugin package:
    * `@azure/identity-vscode`. If this package is not installed and registered
    * using the plugin API (`useIdentityPlugin`), then authentication using

sdk/identity/identity/src/credentials/deviceCodeCredential.browser.ts

@@ -8,7 +8,14 @@ import { credentialLogger, formatError } from "../util/logging";
 const BrowserNotSupportedError = new Error("DeviceCodeCredential is not supported in the browser.");
 const logger = credentialLogger("DeviceCodeCredential");
 
+/**
+ * Enables authentication to Azure Active Directory using a device code
+ * that the user can enter into https://microsoft.com/devicelogin.
+ */
 export class DeviceCodeCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/deviceCodeCredential.ts

@@ -32,6 +32,20 @@ export class DeviceCodeCredential implements TokenCredential {
    * Creates an instance of DeviceCodeCredential with the details needed
    * to initiate the device code authorization flow with Azure Active Directory.
    *
+   * A message will be logged, giving users a code that they can use to authenticate once they go to https://microsoft.com/devicelogin
+   *
+   * Developers can configure how this message is shown by passing a custom `userPromptCallback`:
+   *
+   * ```js
+   * const credential = new DeviceCodeCredential({
+   *   tenantId: env.AZURE_TENANT_ID,
+   *   clientId: env.AZURE_CLIENT_ID,
+   *   userPromptCallback: (info) => {
+   *     console.log("CUSTOMIZED PROMPT CALLBACK", info.message);
+   *   }
+   * });
+   * ```
+   *
    * @param options - Options for configuring the client which makes the authentication requests.
    */
   constructor(options?: DeviceCodeCredentialOptions) {

sdk/identity/identity/src/credentials/environmentCredential.browser.ts

@@ -10,7 +10,14 @@ const BrowserNotSupportedError = new Error(
 );
 const logger = credentialLogger("EnvironmentCredential");
 
+/**
+ * Enables authentication to Azure Active Directory using client secret
+ * details configured in environment variables
+ */
 export class EnvironmentCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/environmentCredential.ts

@@ -41,23 +41,7 @@ export interface EnvironmentCredentialOptions
 
 /**
  * Enables authentication to Azure Active Directory using client secret
- * details configured in the following environment variables:
- *
- * Required environment variables:
- * - `AZURE_TENANT_ID`: The Azure Active Directory tenant (directory) ID.
- * - `AZURE_CLIENT_ID`: The client (application) ID of an App Registration in the tenant.
- *
- * Environment variables used for client credential authentication:
- * - `AZURE_CLIENT_SECRET`: A client secret that was generated for the App Registration.
- * - `AZURE_CLIENT_CERTIFICATE_PATH`: The path to a PEM certificate to use during the authentication, instead of the client secret.
- *
- * Alternatively, users can provide environment variables for username and password authentication:
- * - `AZURE_USERNAME`: Username to authenticate with.
- * - `AZURE_PASSWORD`: Password to authenticate with.
- *
- * This credential ultimately uses a {@link ClientSecretCredential} to
- * perform the authentication using these details.  Please consult the
- * documentation of that class for more details.
+ * details configured in environment variables
  */
 export class EnvironmentCredential implements TokenCredential {
   private _credential?:

sdk/identity/identity/src/credentials/interactiveBrowserCredential.browser.ts

@@ -19,13 +19,6 @@ const logger = credentialLogger("InteractiveBrowserCredential");
 /**
  * Enables authentication to Azure Active Directory inside of the web browser
  * using the interactive login flow.
- *
- * This credential uses the [Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow).
- * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service.
- * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started.
- *
- * It's recommended that the AAD Applications used are configured to authenticate using Single Page Applications.
- * More information here: [link](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#redirect-uri-msaljs-20-with-auth-code-flow).
  */
 export class InteractiveBrowserCredential implements TokenCredential {
   private msalFlow: MsalFlow;
@@ -36,6 +29,13 @@ export class InteractiveBrowserCredential implements TokenCredential {
    * details needed to authenticate against Azure Active Directory with
    * a user identity.
    *
+   * This credential uses the [Authorization Code Flow](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow).
+   * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service.
+   * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started.
+   *
+   * It's recommended that the AAD Applications used are configured to authenticate using Single Page Applications.
+   * More information here: [link](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#redirect-uri-msaljs-20-with-auth-code-flow).
+   *
    * @param options - Options for configuring the client which makes the authentication request.
    */
   constructor(

sdk/identity/identity/src/credentials/interactiveBrowserCredential.ts

@@ -20,13 +20,6 @@ const logger = credentialLogger("InteractiveBrowserCredential");
 /**
  * Enables authentication to Azure Active Directory inside of the web browser
  * using the interactive login flow.
- *
- * This credential uses the [Authorization Code Flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow).
- * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service.
- * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started.
- *
- * For Node.js, if a `clientId` is provided, the Azure Active Directory application will need to be configured to have a "Mobile and desktop applications" redirect endpoint.
- * Follow our guide on [setting up Redirect URIs for Desktop apps that calls to web APIs](https://docs.microsoft.com/azure/active-directory/develop/scenario-desktop-app-registration#redirect-uris).
  */
 export class InteractiveBrowserCredential implements TokenCredential {
   private msalFlow: MsalFlow;
@@ -35,6 +28,13 @@ export class InteractiveBrowserCredential implements TokenCredential {
   /**
    * Creates an instance of InteractiveBrowserCredential with the details needed.
    *
+   * This credential uses the [Authorization Code Flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow).
+   * On Node.js, it will open a browser window while it listens for a redirect response from the authentication service.
+   * On browsers, it authenticates via popups. The `loginStyle` optional parameter can be set to `redirect` to authenticate by redirecting the user to an Azure secure login page, which then will redirect the user back to the web application where the authentication started.
+   *
+   * For Node.js, if a `clientId` is provided, the Azure Active Directory application will need to be configured to have a "Mobile and desktop applications" redirect endpoint.
+   * Follow our guide on [setting up Redirect URIs for Desktop apps that calls to web APIs](https://docs.microsoft.com/azure/active-directory/develop/scenario-desktop-app-registration#redirect-uris).
+   *
    * @param options - Options for configuring the client which makes the authentication requests.
    */
   constructor(

sdk/identity/identity/src/credentials/onBehalfOfCredential.browser.ts

@@ -8,7 +8,13 @@ const credentialName = "OnBehalfOfCredential";
 const BrowserNotSupportedError = new Error(`${credentialName}: Not supported in the browser.`);
 const logger = credentialLogger(credentialName);
 
+/**
+ * Enables authentication to Azure Active Directory using the [On Behalf Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).
+ */
 export class OnBehalfOfCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/usernamePasswordCredential.ts

@@ -17,8 +17,6 @@ const logger = credentialLogger("UsernamePasswordCredential");
  * trust so you should only use it when other, more secure credential
  * types can't be used.
  */
-// We'll be using InteractiveCredential as the base of this class, which requires us to support authenticate(),
-// to reduce the number of times we send the password over the network.
 export class UsernamePasswordCredential implements TokenCredential {
   private msalFlow: MsalFlow;
 

sdk/identity/identity/src/credentials/visualStudioCodeCredential.browser.ts

@@ -18,7 +18,13 @@ export const vsCodeCredentialControl = {
   }
 };
 
+/**
+ * Connects to Azure using the credential provided by the VSCode extension 'Azure Account'.
+ */
 export class VisualStudioCodeCredential implements TokenCredential {
+  /**
+   * Only available in Node.js
+   */
   constructor() {
     logger.info(formatError("", BrowserNotSupportedError));
     throw BrowserNotSupportedError;

sdk/identity/identity/src/credentials/visualStudioCodeCredential.ts

@@ -95,7 +95,7 @@ export interface VisualStudioCodeCredentialOptions extends TokenCredentialOption
 }
 
 /**
- * Connect to Azure using the credential provided by the VSCode extension 'Azure Account'.
+ * Connects to Azure using the credential provided by the VSCode extension 'Azure Account'.
  * Once the user has logged in via the extension, this credential can share the same refresh token
  * that is cached by the extension.
  */