Add an Azure Resources API (v4) authentication layer

api/src/auth/credentialManager/AzExtCredentialManager.ts

@@ -0,0 +1,16 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+export interface AzExtCredentialManager {
+    createCredential(extensionId: string): string | Promise<string>;
+    verifyCredential(credential: string, extensionId?: string): boolean | Promise<boolean>;
+
+    /**
+     * Masks sensitive information from a given string to ensure private credential management keys from the manager are not exposed.
+     * @param data - The string to be processed.
+     * @returns The same string stripped of any sensitive credentials.
+     */
+    maskCredentials(data: string): string;
+}

api/src/auth/credentialManager/AzExtUUIDCredentialManager.ts

@@ -0,0 +1,39 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as crypto from "crypto";
+import { maskValue } from "../../utils/maskValue";
+import { AzExtCredentialManager } from "./AzExtCredentialManager";
+
+/**
+ * A simple, light-weight credential manager that issues and tracks randomly generated UUIDs for extension verification.
+ */
+export class AzExtUUIDCredentialManager implements AzExtCredentialManager {
+    #uuidMap: Map<string, string>;
+
+    constructor() {
+        this.#uuidMap = new Map();
+    }
+
+    createCredential(extensionId: string): string {
+        const uuid: string = crypto.randomUUID();
+        this.#uuidMap.set(extensionId, uuid);
+        return uuid;
+    }
+
+    verifyCredential(credential: string, extensionId: string): boolean {
+        if (!credential || !extensionId) {
+            return false;
+        }
+        return credential === this.#uuidMap.get(extensionId);
+    }
+
+    maskCredentials(data: string): string {
+        for (const uuid of this.#uuidMap.values()) {
+            data = maskValue(data, uuid);
+        }
+        return data;
+    }
+}

api/src/extensionApi.ts

@@ -9,6 +9,14 @@ import { AzureExtensionApi } from "./utils/apiUtils";
 /**
  * The current (v2) Azure Resources extension API.
  */
-export interface AzureResourcesExtensionApi extends AzureExtensionApi {
+export interface AzureResourcesExtensionApi extends Omit<AzureExtensionApi, 'receiveAzureResourcesApiSession'> {
     resources: ResourcesApi;
 }
+
+/**
+ * The authentication layer (v4) protecting the core Azure Resources extension API.
+ */
+export interface AzureResourcesExtensionAuthApi extends Omit<AzureExtensionApi, 'receiveAzureResourcesApiSession'> {
+    getAzureResourcesApis(clientExtensionId: string, azureResourcesCredential: string, azureResourcesApiVersions: string[]): Promise<(AzureExtensionApi | undefined)[]>;
+    createAzureResourcesApiSession(clientExtensionId: string, clientExtensionVersion: string, clientExtensionCredential: string): Promise<void>;
+}

api/src/utils/apiUtils.ts

@@ -10,6 +10,16 @@ export interface AzureExtensionApi {
      * The API version for this extension. It should be versioned separately from the extension and ideally remains backwards compatible.
      */
     apiVersion: string;
+
+    /**
+     * Optional endpoint which Azure client extensions should implement in order to receive an Azure Resources API session.
+     * See: https://github.com/microsoft/vscode-azureresourcegroups/blob/main/api/src/auth/README.md
+     *
+     * @param azureResourcesCredential - The credential to use when requesting the Azure Resources API
+     * @param clientCredential - The client verification credential initially generated by the client and passed to the Azure Resources API when requesting a new session.
+     * This credential is used to verify that the real Azure Resources extension is the one providing back the session credential.
+     */
+    receiveAzureResourcesApiSession?(azureResourcesCredential: string, clientCredential: string): void | Promise<void>;
 }
 
 export interface GetApiOptions {
@@ -62,20 +72,12 @@ export namespace apiUtils {
     }
 
     /**
-     * Get extension exports for the extension with the given id. Activates extension first if needed.
+     * Activates an extension and returns its exports.
      *
      * @returns `undefined` if the extension is not installed
      */
     export async function getExtensionExports<T>(extensionId: string): Promise<T | undefined> {
         const extension: vscode.Extension<T> | undefined = vscode.extensions.getExtension(extensionId);
-        if (extension) {
-            if (!extension.isActive) {
-                await extension.activate();
-            }
-
-            return extension.exports;
-        }
-
-        return undefined;
+        return await extension?.activate();
     }
 }

api/src/utils/getApi.ts

@@ -7,6 +7,10 @@ import * as vscode from 'vscode';
 import type { AzureResourcesExtensionApi } from '../extensionApi';
 import { apiUtils, GetApiOptions } from "./apiUtils";
 
+/**
+ * @deprecated The Azure Resources core API should be accessed through the new auth layer.
+ * See: https://github.com/microsoft/vscode-azureresourcegroups/blob/main/api/src/auth/README.md
+ * */
 export async function getAzureResourcesExtensionApi(extensionContext: vscode.ExtensionContext, apiVersionRange: '2.0.0', options?: GetApiOptions): Promise<AzureResourcesExtensionApi> {
     return apiUtils.getAzureExtensionApi<AzureResourcesExtensionApi>(extensionContext, 'ms-azuretools.vscode-azureresourcegroups', apiVersionRange, options);
 }

api/src/utils/maskValue.ts

@@ -0,0 +1,15 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+// Sourced from @microsoft/vscode-azext-utils
+export function maskValue(data: string, valueToMask: string | undefined): string {
+    if (valueToMask) {
+        const formsOfValue: string[] = [valueToMask, encodeURIComponent(valueToMask)];
+        for (const v of formsOfValue) {
+            data = data.replace(new RegExp(escape(v), 'gi'), '---');
+        }
+    }
+    return data;
+}

src/api/auth/createApiSession/CreateApiSessionInternalContext.ts

@@ -0,0 +1,23 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { IActionContext } from "@microsoft/vscode-azext-utils";
+import { AzExtCredentialManager } from "api/src/auth/credentialManager/AzExtCredentialManager";
+import { AzureExtensionApi } from "api/src/utils/apiUtils";
+
+export interface CreateApiSessionInternalContext extends IActionContext {
+    credentialManager: AzExtCredentialManager;
+    clientExtensionId: string;
+    clientExtensionVersion: string;
+    clientExtensionCredential: string;
+
+    /**
+     * An optional API provider to be used in lieu of the VS Code API `vscode.extension.getExtension()`.
+     * This should _NOT_ be defined in production environments.
+     */
+    clientApiProvider?: CreateApiSessionExtensionProvider;
+}
+
+export type CreateApiSessionExtensionProvider = { getApi(clientExtensionId: string, clientExtensionVersion: string): AzureExtensionApi };

src/api/auth/createApiSession/createApiSessionInternal.ts

@@ -0,0 +1,43 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { IParsedError, maskUserInfo, parseError } from "@microsoft/vscode-azext-utils";
+import { apiUtils } from "../../../../api/src/utils/apiUtils";
+import { azureExtensions } from "../../../azureExtensions";
+import { ext } from '../../../extensionVariables';
+import { localize } from "../../../utils/localize";
+import { CreateApiSessionInternalContext } from './CreateApiSessionInternalContext';
+
+const allowedExtensionIds = new Set(azureExtensions.map(extension => `${extension.publisher.toLowerCase()}.${extension.name.toLowerCase()}`));
+
+export async function createApiSessionInternal(context: CreateApiSessionInternalContext): Promise<void> {
+    context.telemetry.properties.clientExtensionId = context.clientExtensionId;
+    context.telemetry.properties.clientExtensionVersion = context.clientExtensionVersion;
+
+    if (!allowedExtensionIds.has(context.clientExtensionId)) {
+        context.telemetry.properties.allowedExtension = 'false';
+        ext.outputChannel.warn(localize('createResourcesApiSession.denied', 'Azure Resources API session denied for extension "{0}".', context.clientExtensionId));
+        throw new Error('🧙 No, thank you! We don\'t want any more visitors, well-wishers, or distant relations! 🧝🦶');
+    }
+
+    context.telemetry.properties.allowedExtension = 'true';
+
+    try {
+        const clientApi = context.clientApiProvider?.getApi(context.clientExtensionId, context.clientExtensionVersion) ??
+            await apiUtils.getAzureExtensionApi(ext.context, context.clientExtensionId, context.clientExtensionVersion);
+
+        const azureResourcesCredential: string = await context.credentialManager.createCredential(context.clientExtensionId);
+        await clientApi.receiveAzureResourcesApiSession?.(azureResourcesCredential, context.clientExtensionCredential);
+    } catch (err) {
+        const failed: string = localize('createResourcesApiSession.failed', 'Failed to create Azure Resources API session for extension "{0}".', context.clientExtensionId);
+        ext.outputChannel.error(failed);
+
+        const perr: IParsedError = parseError(err);
+        const perrMessage: string = context.credentialManager.maskCredentials(perr.message);
+        context.telemetry.properties.createResourcesApiSessionError = maskUserInfo(perrMessage, []);
+        ext.outputChannel.error(perrMessage);
+        throw new Error(failed);
+    }
+}

src/api/auth/createAuthApiFactory.ts

@@ -0,0 +1,93 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { apiUtils, AzureExtensionApiFactory, callWithTelemetryAndErrorHandling, GetApiOptions, IActionContext } from '@microsoft/vscode-azext-utils';
+import { AzExtCredentialManager } from '../../../api/src/auth/credentialManager/AzExtCredentialManager';
+import { AzExtUUIDCredentialManager } from '../../../api/src/auth/credentialManager/AzExtUUIDCredentialManager';
+import { AzureResourcesAuthApiInternal } from '../../hostapi.v4.internal';
+import { createApiSessionInternal } from './createApiSession/createApiSessionInternal';
+import { CreateApiSessionExtensionProvider, CreateApiSessionInternalContext } from './createApiSession/CreateApiSessionInternalContext';
+import { getApiVerifyError, verifyApiSessionInternal } from './verifyApiSession/verifyApiSessionInternal';
+import { VerifyApiSessionInternalContext } from './verifyApiSession/VerifyApiSessionInternalContext';
+
+const v4: string = '4.0.0';
+
+export type AuthApiFactoryDependencies = {
+    /**
+     * An optional credential manager used for issuing and verifying Azure Resources API credentials. If none are supplied, a simple UUID credential manager will be used.
+     * @test Use this to more easily mock and inspect the behavior of the underlying credential manager.
+     */
+    credentialManager?: AzExtCredentialManager;
+    /**
+     * An optional API provider to be used in lieu of the VS Code extension provider `vscode.extension.getExtension()`.
+     * This should _NOT_ be defined in production environments.
+     * @test Use this to more easily mock and inject custom client extension API exports.
+     */
+    clientApiProvider?: CreateApiSessionExtensionProvider;
+}
+
+export function createAuthApiFactory(coreApiProvider: apiUtils.AzureExtensionApiProvider, customDependencies?: AuthApiFactoryDependencies): AzureExtensionApiFactory<AzureResourcesAuthApiInternal> {
+    const credentialManager = customDependencies?.credentialManager ?? new AzExtUUIDCredentialManager();
+    const clientApiProvider = customDependencies?.clientApiProvider;
+
+    return {
+        apiVersion: v4,
+        createApi: (options?: GetApiOptions) => {
+            return {
+                apiVersion: v4,
+
+                getAzureResourcesApis: async (clientExtensionId: string, azureResourcesCredential: string, azureResourcesApiVersions: string[]) => {
+                    return await callWithTelemetryAndErrorHandling('api.getAzureResourcesApis', async (context: IActionContext) => {
+                        setTelemetryAndErrorHandling(context, options?.extensionId);
+
+                        const verified: boolean = await verifyApiSessionInternal(Object.assign(context, {
+                            credentialManager,
+                            clientExtensionId: clientExtensionId?.toLowerCase(),
+                            azureResourcesCredential,
+                        }) satisfies VerifyApiSessionInternalContext);
+
+                        if (!verified) {
+                            throw new Error(getApiVerifyError(clientExtensionId));
+                        }
+
+                        return azureResourcesApiVersions
+                            .map((apiVersion) => {
+                                try {
+                                    return coreApiProvider.getApi(apiVersion, options);
+                                } catch {
+                                    return undefined;
+                                }
+                            });
+
+                    }) ?? [];
+                },
+
+                createAzureResourcesApiSession: async (clientExtensionId: string, clientExtensionVersion: string, clientExtensionCredential: string) => {
+                    return await callWithTelemetryAndErrorHandling('api.createAzureResourcesApiSession', async (context: IActionContext) => {
+                        setTelemetryAndErrorHandling(context, options?.extensionId);
+
+                        return await createApiSessionInternal(Object.assign(context, {
+                            credentialManager,
+                            clientExtensionId: clientExtensionId?.toLowerCase(),
+                            clientExtensionVersion,
+                            clientExtensionCredential,
+                            clientApiProvider,
+                        }) satisfies CreateApiSessionInternalContext);
+                    });
+                },
+
+            };
+        },
+    };
+}
+
+function setTelemetryAndErrorHandling(context: IActionContext, extensionId?: string): void {
+    context.telemetry.properties.callingExtensionId = extensionId;
+    context.telemetry.properties.isActivationEvent = 'true';
+    context.telemetry.properties.apiVersion = v4;
+    context.errorHandling.rethrow = true;
+    context.errorHandling.suppressDisplay = true;
+    context.errorHandling.suppressReportIssue = true;
+}

src/api/auth/verifyApiSession/VerifyApiSessionInternalContext.ts

@@ -0,0 +1,13 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { IActionContext } from "@microsoft/vscode-azext-utils";
+import { AzExtCredentialManager } from "api/src/auth/credentialManager/AzExtCredentialManager";
+
+export interface VerifyApiSessionInternalContext extends IActionContext {
+    credentialManager: AzExtCredentialManager;
+    clientExtensionId: string;
+    azureResourcesCredential: string;
+}

src/api/auth/verifyApiSession/verifyApiSessionInternal.ts

@@ -0,0 +1,34 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { l10n } from 'vscode';
+import { ext } from '../../../extensionVariables';
+import { VerifyApiSessionInternalContext } from './VerifyApiSessionInternalContext';
+
+export const getApiVerifyError = (clientExtensionId?: string) => `${clientExtensionId || 'Unknown Extension'} - 🧙 YOU SHALL NOT PASS! 🔥`;
+
+export async function verifyApiSessionInternal(context: VerifyApiSessionInternalContext): Promise<boolean> {
+    const apiVerifyError: string = getApiVerifyError(context.clientExtensionId);
+
+    if (!context.clientExtensionId || !context.azureResourcesCredential) {
+        context.telemetry.properties.deniedReason = 'missingDetails';
+        throw new Error(apiVerifyError);
+    }
+
+    context.telemetry.properties.clientExtensionId = context.clientExtensionId;
+
+    let verified: boolean | undefined;
+    try {
+        verified = await context.credentialManager.verifyCredential(context.azureResourcesCredential, context.clientExtensionId);
+    } catch { /** Skip; handle below */ }
+
+    if (!verified) {
+        context.telemetry.properties.deniedReason = 'failedVerification';
+        ext.outputChannel.warn(l10n.t('Extension claiming to be "{0}" provided an access token that failed verification.', context.clientExtensionId));
+        throw new Error(apiVerifyError);
+    }
+
+    return verified;
+}