[Identity] Support for tenant Id Challenges / tenant discovery in ClientCredentials

sdk/core/core-auth/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 1.3.1 (Unreleased)
 
+- Added `tenantId`, which is used to enable multi-tenant authentication.
 
 ## 1.3.0 (2021-03-30)
 

sdk/core/core-auth/review/core-auth.api.md

@@ -47,6 +47,7 @@ export interface GetTokenOptions {
     requestOptions?: {
         timeout?: number;
     };
+    tenantId?: string;
     tracingOptions?: {
         spanOptions?: SpanOptions;
         tracingContext?: Context;

sdk/core/core-auth/src/tokenCredential.ts

@@ -52,6 +52,11 @@ export interface GetTokenOptions {
      */
     tracingContext?: Context;
   };
+
+  /**
+   * Allows specifying a tenantId. Useful to handle challenges that provide tenant Id hints.
+   */
+  tenantId?: string;
 }
 
 /**

sdk/identity/identity/CHANGELOG.md

@@ -14,6 +14,11 @@
   - Added `regionalAuthority` property to `ClientSecretCredentialOptions` and `ClientCertificateCredentialOptions`.
   - If instead of a region, `AutoDiscoverRegion` is specified as the value for `regionalAuthority`, MSAL will be used to attempt to discover the region.
   - A region can also be specified through the `AZURE_REGIONAL_AUTHORITY_NAME` environment variable.
+- The `AzureCliCredential` now receives an `AzureCliCredentialOptions` object, which has the same structure of the `TokenCredentialOptions`, but with an extra optional `tenantId`.
+- The `AzurePowerShellCredential` now receives an `AzurePowerShellCredentialOptions` object, which has the same structure of the `TokenCredentialOptions`, but with an extra optional `tenantId`.
+- All of the credentials now accept `allowMultiTenantAuthentication`, and as long as they allow configuring a `tenantId`, they now also work with the `GetTokenOptions` new property: `tenantId`.
+  - If a tenant is specified, any `getToken` request that receives a `tenantId` that doesn't match the credential's `tenantId` will throw an error, unless `getToken` gets called with the `allowMultiTenantAuthentication` property set to true.
+  - If multi-tenant authentication is allowed, a `tenantId` received through `GetTokenOptions` will be used for that specific request for token instead of the `tenantId` configured when the credential was initialized.
 
 ### Breaking Changes
 

sdk/identity/identity/review/identity.api.md

@@ -66,12 +66,24 @@ export enum AzureAuthorityHosts {
 
 // @public
 export class AzureCliCredential implements TokenCredential {
+    constructor(options?: AzureCliCredentialOptions);
     getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
+    }
+
+// @public
+export interface AzureCliCredentialOptions extends TokenCredentialOptions {
+    tenantId?: string;
 }
 
 // @public
 export class AzurePowerShellCredential implements TokenCredential {
+    constructor(options?: AzurePowerShellCredentialOptions);
     getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>;
+    }
+
+// @public
+export interface AzurePowerShellCredentialOptions extends TokenCredentialOptions {
+    tenantId?: string;
 }
 
 // @public
@@ -295,6 +307,7 @@ export { TokenCredential }
 
 // @public
 export interface TokenCredentialOptions extends PipelineOptions {
+    allowMultiTenantAuthentication?: boolean;
     authorityHost?: string;
 }
 
@@ -314,7 +327,7 @@ export interface UsernamePasswordCredentialOptions extends TokenCredentialOption
 // @public
 export class VisualStudioCodeCredential implements TokenCredential {
     constructor(options?: VisualStudioCodeCredentialOptions);
-    getToken(scopes: string | string[], _options?: GetTokenOptions): Promise<AccessToken>;
+    getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
     }
 
 // @public

sdk/identity/identity/src/client/identityClient.ts

@@ -313,4 +313,9 @@ export interface TokenCredentialOptions extends PipelineOptions {
    * The default is "https://login.microsoftonline.com".
    */
   authorityHost?: string;
+
+  /**
+   * If set to true, allows authentication flows to change the tenantId of the request if a different tenantId is received from a challenge or through a direct getToken call.
+   */
+  allowMultiTenantAuthentication?: boolean;
 }

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

@@ -12,6 +12,7 @@ import { SpanStatusCode } from "@azure/core-tracing";
 import { credentialLogger, formatSuccess, formatError } from "../util/logging";
 import { getIdentityTokenEndpointSuffix } from "../util/identityTokenEndpoint";
 import { checkTenantId } from "../util/checkTenantId";
+import { processMultiTenantRequest } from "../util/validateMultiTenant";
 
 const logger = credentialLogger("AuthorizationCodeCredential");
 
@@ -30,6 +31,7 @@ export class AuthorizationCodeCredential implements TokenCredential {
   private authorizationCode: string;
   private redirectUri: string;
   private lastTokenResponse: TokenResponse | null = null;
+  private allowMultiTenantAuthentication?: boolean;
 
   /**
    * Creates an instance of CodeFlowCredential with the details needed
@@ -105,6 +107,7 @@ export class AuthorizationCodeCredential implements TokenCredential {
 
     this.clientId = clientId;
     this.tenantId = tenantId;
+    this.allowMultiTenantAuthentication = options?.allowMultiTenantAuthentication;
 
     if (typeof redirectUriOrOptions === "string") {
       // the clientId+clientSecret constructor
@@ -135,6 +138,12 @@ export class AuthorizationCodeCredential implements TokenCredential {
     scopes: string | string[],
     options?: GetTokenOptions
   ): Promise<AccessToken> {
+    const tenantId = processMultiTenantRequest(
+      this.tenantId,
+      this.allowMultiTenantAuthentication,
+      options
+    )!;
+
     const { span, updatedOptions } = createSpan("AuthorizationCodeCredential-getToken", options);
     try {
       let tokenResponse: TokenResponse | null = null;
@@ -146,7 +155,7 @@ export class AuthorizationCodeCredential implements TokenCredential {
       // Try to use the refresh token first
       if (this.lastTokenResponse && this.lastTokenResponse.refreshToken) {
         tokenResponse = await this.identityClient.refreshAccessToken(
-          this.tenantId,
+          tenantId,
           this.clientId,
           scopeString,
           this.lastTokenResponse.refreshToken,
@@ -157,9 +166,9 @@ export class AuthorizationCodeCredential implements TokenCredential {
       }
 
       if (tokenResponse === null) {
-        const urlSuffix = getIdentityTokenEndpointSuffix(this.tenantId);
+        const urlSuffix = getIdentityTokenEndpointSuffix(tenantId);
         const webResource = this.identityClient.createWebResource({
-          url: `${this.identityClient.authorityHost}/${this.tenantId}/${urlSuffix}`,
+          url: `${this.identityClient.authorityHost}/${tenantId}/${urlSuffix}`,
           method: "POST",
           disableJsonStringifyOnBody: true,
           deserializationMapper: undefined,

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

@@ -9,6 +9,8 @@ import { SpanStatusCode } from "@azure/core-tracing";
 import { credentialLogger, formatSuccess, formatError } from "../util/logging";
 import * as child_process from "child_process";
 import { ensureValidScope, getScopeResource } from "../util/scopeUtils";
+import { AzureCliCredentialOptions } from "./azureCliCredentialOptions";
+import { processMultiTenantRequest } from "../util/validateMultiTenant";
 
 /**
  * Mockable reference to the CLI credential cliCredentialFunctions
@@ -35,13 +37,26 @@ export const cliCredentialInternals = {
    * @internal
    */
   async getAzureCliAccessToken(
-    resource: string
+    resource: string,
+    tenantId?: string
   ): Promise<{ stdout: string; stderr: string; error: Error | null }> {
+    let tenantSection: string[] = [];
+    if (tenantId) {
+      tenantSection = ["--tenant", tenantId];
+    }
     return new Promise((resolve, reject) => {
       try {
         child_process.execFile(
           "az",
-          ["account", "get-access-token", "--output", "json", "--resource", resource],
+          [
+            "account",
+            "get-access-token",
+            "--output",
+            "json",
+            "--resource",
+            ...tenantSection,
+            resource
+          ],
           { cwd: cliCredentialInternals.getSafeWorkingDir() },
           (error, stdout, stderr) => {
             resolve({ stdout: stdout, stderr: stderr, error });
@@ -65,6 +80,19 @@ const logger = credentialLogger("AzureCliCredential");
  * in via the 'az' tool using the command "az login" from the commandline.
  */
 export class AzureCliCredential implements TokenCredential {
+  private tenantId?: string;
+  private allowMultiTenantAuthentication?: boolean;
+
+  /**
+   * Creates an instance of the {@link AzureCliCredential}.
+   *
+   * @param options - Options, to optionally allow multi-tenant requests.
+   */
+  constructor(options?: AzureCliCredentialOptions) {
+    this.tenantId = options?.tenantId;
+    this.allowMultiTenantAuthentication = options?.allowMultiTenantAuthentication;
+  }
+
   /**
    * Authenticates with Azure Active Directory and returns an access token if successful.
    * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
@@ -77,9 +105,13 @@ export class AzureCliCredential implements TokenCredential {
     scopes: string | string[],
     options?: GetTokenOptions
   ): Promise<AccessToken> {
+    const tenantId = processMultiTenantRequest(
+      this.tenantId,
+      this.allowMultiTenantAuthentication,
+      options
+    );
     const scope = typeof scopes === "string" ? scopes : scopes[0];
     logger.getToken.info(`Using the scope ${scope}`);
-
     ensureValidScope(scope, logger);
     const resource = getScopeResource(scope);
 
@@ -88,7 +120,7 @@ export class AzureCliCredential implements TokenCredential {
     const { span } = createSpan("AzureCliCredential-getToken", options);
 
     try {
-      const obj = await cliCredentialInternals.getAzureCliAccessToken(resource);
+      const obj = await cliCredentialInternals.getAzureCliAccessToken(resource, tenantId);
       if (obj.stderr) {
         const isLoginError = obj.stderr.match("(.*)az login(.*)");
         const isNotInstallError =

sdk/identity/identity/src/credentials/azureCliCredentialOptions.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { TokenCredentialOptions } from "../client/identityClient";
+
+/**
+ * Options for the {@link AzureCliCredential}
+ */
+export interface AzureCliCredentialOptions extends TokenCredentialOptions {
+  /**
+   * Allows specifying a tenant ID
+   */
+  tenantId?: string;
+}

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

@@ -8,6 +8,8 @@ import { credentialLogger, formatSuccess, formatError } from "../util/logging";
 import { trace } from "../util/tracing";
 import { ensureValidScope, getScopeResource } from "../util/scopeUtils";
 import { processUtils } from "../util/processUtils";
+import { AzurePowerShellCredentialOptions } from "./azurePowerShellCredentialOptions";
+import { processMultiTenantRequest } from "../util/validateMultiTenant";
 
 const logger = credentialLogger("AzurePowerShellCredential");
 
@@ -92,12 +94,26 @@ if (isWindows) {
  * `Connect-AzAccount` from the command line.
  */
 export class AzurePowerShellCredential implements TokenCredential {
+  private tenantId?: string;
+  private allowMultiTenantAuthentication?: boolean;
+
+  /**
+   * Creates an instance of the {@link AzurePowershellCredential}.
+   *
+   * @param options - Options, to optionally allow multi-tenant requests.
+   */
+  constructor(options?: AzurePowerShellCredentialOptions) {
+    this.tenantId = options?.tenantId;
+    this.allowMultiTenantAuthentication = options?.allowMultiTenantAuthentication;
+  }
+
   /**
    * Gets the access token from Azure PowerShell
    * @param resource - The resource to use when getting the token
    */
   private async getAzurePowerShellAccessToken(
-    resource: string
+    resource: string,
+    tenantId?: string
   ): Promise<{ Token: string; ExpiresOn: string }> {
     // Clone the stack to avoid mutating it while iterating
     for (const powerShellCommand of [...commandStack]) {
@@ -109,6 +125,11 @@ export class AzurePowerShellCredential implements TokenCredential {
         continue;
       }
 
+      let tenantSection = "";
+      if (tenantId) {
+        tenantSection = `-TenantId "${tenantId}"`;
+      }
+
       const results = await runCommands([
         [
           powerShellCommand,
@@ -118,7 +139,7 @@ export class AzurePowerShellCredential implements TokenCredential {
         [
           powerShellCommand,
           "-Command",
-          `Get-AzAccessToken -ResourceUrl "${resource}" | ConvertTo-Json`
+          `Get-AzAccessToken ${tenantSection} -ResourceUrl "${resource}" | ConvertTo-Json`
         ]
       ]);
 
@@ -145,15 +166,18 @@ export class AzurePowerShellCredential implements TokenCredential {
     options: GetTokenOptions = {}
   ): Promise<AccessToken | null> {
     return trace(`${this.constructor.name}.getToken`, options, async () => {
+      const tenantId = processMultiTenantRequest(
+        this.tenantId,
+        this.allowMultiTenantAuthentication,
+        options
+      );
       const scope = typeof scopes === "string" ? scopes : scopes[0];
-
-      logger.getToken.info(`Using the scope ${scope}`);
-
       ensureValidScope(scope, logger);
+      logger.getToken.info(`Using the scope ${scope}`);
       const resource = getScopeResource(scope);
 
       try {
-        const response = await this.getAzurePowerShellAccessToken(resource);
+        const response = await this.getAzurePowerShellAccessToken(resource, tenantId);
         logger.getToken.info(formatSuccess(scopes));
         return {
           token: response.Token,

sdk/identity/identity/src/credentials/azurePowerShellCredentialOptions.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { TokenCredentialOptions } from "../client/identityClient";
+
+/**
+ * Options for the {@link AzurePowerShellCredential}
+ */
+export interface AzurePowerShellCredentialOptions extends TokenCredentialOptions {
+  /**
+   * Allows specifying a tenant ID
+   */
+  tenantId?: string;
+}

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

@@ -12,6 +12,7 @@ import { IdentityClient, TokenCredentialOptions } from "../client/identityClient
 import { AzureAuthorityHosts } from "../constants";
 import { checkTenantId } from "../util/checkTenantId";
 import { credentialLogger, formatError, formatSuccess } from "../util/logging";
+import { processMultiTenantRequest } from "../util/validateMultiTenant";
 import { VSCodeCredentialFinder } from "./visualStudioCodeCredentialExtension";
 
 const CommonTenantId = "common";
@@ -102,6 +103,7 @@ export class VisualStudioCodeCredential implements TokenCredential {
   private identityClient: IdentityClient;
   private tenantId: string;
   private cloudName: VSCodeCloudNames;
+  private allowMultiTenantAuthentication?: boolean;
 
   /**
    * Creates an instance of VisualStudioCodeCredential to use for automatically authenticating via VSCode.
@@ -127,6 +129,7 @@ export class VisualStudioCodeCredential implements TokenCredential {
     } else {
       this.tenantId = CommonTenantId;
     }
+    this.allowMultiTenantAuthentication = options?.allowMultiTenantAuthentication;
 
     checkUnsupportedTenant(this.tenantId);
   }
@@ -168,9 +171,15 @@ export class VisualStudioCodeCredential implements TokenCredential {
    */
   public async getToken(
     scopes: string | string[],
-    _options?: GetTokenOptions
+    options?: GetTokenOptions
   ): Promise<AccessToken> {
     await this.prepareOnce();
+    const tenantId = processMultiTenantRequest(
+      this.tenantId,
+      this.allowMultiTenantAuthentication,
+      options
+    )!;
+
     if (findCredentials === undefined) {
       throw new CredentialUnavailableError(
         "No implementation of VisualStudioCodeCredential is available (do you need to install and use the `@azure/identity-vscode` extension package?)"
@@ -206,7 +215,7 @@ export class VisualStudioCodeCredential implements TokenCredential {
 
     if (refreshToken) {
       const tokenResponse = await this.identityClient.refreshAccessToken(
-        this.tenantId,
+        tenantId,
         AzureAccountClientId,
         scopeString,
         refreshToken,