@azure/msal-common 14.0.2 → 14.1.0-alpha.0

package/src/authority/AuthorityOptions.ts

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ProtocolMode } from "./ProtocolMode";
+import { OIDCOptions } from "./OIDCOptions";
+import { AzureRegionConfiguration } from "./AzureRegionConfiguration";
+
+export type AuthorityOptions = {
+    protocolMode: ProtocolMode;
+    OIDCOptions?: OIDCOptions | null;
+    knownAuthorities: Array<string>;
+    cloudDiscoveryMetadata: string;
+    authorityMetadata: string;
+    skipAuthorityMetadataCache?: boolean;
+    azureRegionConfiguration?: AzureRegionConfiguration;
+};
+
+export const AzureCloudInstance = {
+    // AzureCloudInstance is not specified.
+    None: "none",
+
+    // Microsoft Azure public cloud
+    AzurePublic: "https://login.microsoftonline.com",
+
+    // Microsoft PPE
+    AzurePpe: "https://login.windows-ppe.net",
+
+    // Microsoft Chinese national/regional cloud
+    AzureChina: "https://login.chinacloudapi.cn",
+
+    // Microsoft German national/regional cloud ("Black Forest")
+    AzureGermany: "https://login.microsoftonline.de",
+
+    // US Government cloud
+    AzureUsGovernment: "https://login.microsoftonline.us",
+} as const;
+export type AzureCloudInstance =
+    (typeof AzureCloudInstance)[keyof typeof AzureCloudInstance];

package/src/authority/AuthorityType.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Authority types supported by MSAL.
+ */
+export const AuthorityType = {
+    Default: 0,
+    Adfs: 1,
+    Dsts: 2,
+    Ciam: 3,
+} as const;
+export type AuthorityType = (typeof AuthorityType)[keyof typeof AuthorityType];

package/src/authority/AzureRegion.ts

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+// The type here is a string instead of enum as the list of regional end points supported is not final yet.
+export type AzureRegion = string;

package/src/authority/AzureRegionConfiguration.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AzureRegion } from "./AzureRegion";
+
+/*
+ * AzureRegionConfiguration
+ * - preferredAzureRegion       - Preferred azure region from the user
+ * - environmentRegionFunc      - Environment specific way of fetching the region from the environment
+ */
+export type AzureRegionConfiguration = {
+    azureRegion?: AzureRegion;
+    environmentRegion: string | undefined;
+};

package/src/authority/CloudDiscoveryMetadata.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type CloudDiscoveryMetadata = {
+    preferred_network: string;
+    preferred_cache: string;
+    aliases: Array<string>;
+};

package/src/authority/CloudInstanceDiscoveryErrorResponse.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * The OpenID Configuration Endpoint Response type. Used by the authority class to get relevant OAuth endpoints.
+ */
+export type CloudInstanceDiscoveryErrorResponse = {
+    error: String;
+    error_description: String;
+    error_codes?: Array<Number>;
+    timestamp?: String;
+    trace_id?: String;
+    correlation_id?: String;
+    error_uri?: String;
+};
+
+export function isCloudInstanceDiscoveryErrorResponse(
+    response: object
+): boolean {
+    return (
+        response.hasOwnProperty("error") &&
+        response.hasOwnProperty("error_description")
+    );
+}

package/src/authority/CloudInstanceDiscoveryResponse.ts

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CloudDiscoveryMetadata } from "./CloudDiscoveryMetadata";
+
+/**
+ * The OpenID Configuration Endpoint Response type. Used by the authority class to get relevant OAuth endpoints.
+ */
+export type CloudInstanceDiscoveryResponse = {
+    tenant_discovery_endpoint: string;
+    metadata: Array<CloudDiscoveryMetadata>;
+};
+
+export function isCloudInstanceDiscoveryResponse(response: object): boolean {
+    return (
+        response.hasOwnProperty("tenant_discovery_endpoint") &&
+        response.hasOwnProperty("metadata")
+    );
+}

package/src/authority/ImdsOptions.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export type ImdsOptions = {
+    headers?: {
+        Metadata: string;
+    };
+};

package/src/authority/OIDCOptions.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ServerResponseType } from "../utils/Constants";
+
+/**
+ * Options for the OIDC protocol mode.
+ */
+export type OIDCOptions = {
+    serverResponseType?: ServerResponseType;
+    defaultScopes?: Array<string>;
+};

package/src/authority/OpenIdConfigResponse.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Tenant Discovery Response which contains the relevant OAuth endpoints and data needed for authentication and authorization.
+ */
+export type OpenIdConfigResponse = {
+    authorization_endpoint: string;
+    token_endpoint: string;
+    end_session_endpoint?: string;
+    issuer: string;
+    jwks_uri: string;
+};
+
+export function isOpenIdConfigResponse(response: object): boolean {
+    return (
+        response.hasOwnProperty("authorization_endpoint") &&
+        response.hasOwnProperty("token_endpoint") &&
+        response.hasOwnProperty("issuer") &&
+        response.hasOwnProperty("jwks_uri")
+    );
+}

package/src/authority/ProtocolMode.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Protocol modes supported by MSAL.
+ */
+export const ProtocolMode = {
+    AAD: "AAD",
+    OIDC: "OIDC",
+} as const;
+export type ProtocolMode = (typeof ProtocolMode)[keyof typeof ProtocolMode];

package/src/authority/RegionDiscovery.ts

@@ -0,0 +1,196 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { INetworkModule } from "../network/INetworkModule";
+import { NetworkResponse } from "../network/NetworkManager";
+import { IMDSBadResponse } from "../response/IMDSBadResponse";
+import {
+    Constants,
+    RegionDiscoverySources,
+    ResponseCodes,
+} from "../utils/Constants";
+import { RegionDiscoveryMetadata } from "./RegionDiscoveryMetadata";
+import { ImdsOptions } from "./ImdsOptions";
+import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient";
+import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent";
+import { invokeAsync } from "../utils/FunctionWrappers";
+import { Logger } from "../logger/Logger";
+
+export class RegionDiscovery {
+    // Network interface to make requests with.
+    protected networkInterface: INetworkModule;
+    // Logger
+    private logger: Logger;
+    // Performance client
+    protected performanceClient: IPerformanceClient | undefined;
+    // CorrelationId
+    protected correlationId: string | undefined;
+    // Options for the IMDS endpoint request
+    protected static IMDS_OPTIONS: ImdsOptions = {
+        headers: {
+            Metadata: "true",
+        },
+    };
+
+    constructor(
+        networkInterface: INetworkModule,
+        logger: Logger,
+        performanceClient?: IPerformanceClient,
+        correlationId?: string
+    ) {
+        this.networkInterface = networkInterface;
+        this.logger = logger;
+        this.performanceClient = performanceClient;
+        this.correlationId = correlationId;
+    }
+
+    /**
+     * Detect the region from the application's environment.
+     *
+     * @returns Promise<string | null>
+     */
+    public async detectRegion(
+        environmentRegion: string | undefined,
+        regionDiscoveryMetadata: RegionDiscoveryMetadata
+    ): Promise<string | null> {
+        this.performanceClient?.addQueueMeasurement(
+            PerformanceEvents.RegionDiscoveryDetectRegion,
+            this.correlationId
+        );
+
+        // Initialize auto detected region with the region from the envrionment
+        let autodetectedRegionName = environmentRegion;
+
+        // Check if a region was detected from the environment, if not, attempt to get the region from IMDS
+        if (!autodetectedRegionName) {
+            const options = RegionDiscovery.IMDS_OPTIONS;
+
+            try {
+                const localIMDSVersionResponse = await invokeAsync(
+                    this.getRegionFromIMDS.bind(this),
+                    PerformanceEvents.RegionDiscoveryGetRegionFromIMDS,
+                    this.logger,
+                    this.performanceClient,
+                    this.correlationId
+                )(Constants.IMDS_VERSION, options);
+                if (
+                    localIMDSVersionResponse.status ===
+                    ResponseCodes.httpSuccess
+                ) {
+                    autodetectedRegionName = localIMDSVersionResponse.body;
+                    regionDiscoveryMetadata.region_source =
+                        RegionDiscoverySources.IMDS;
+                }
+
+                // If the response using the local IMDS version failed, try to fetch the current version of IMDS and retry.
+                if (
+                    localIMDSVersionResponse.status ===
+                    ResponseCodes.httpBadRequest
+                ) {
+                    const currentIMDSVersion = await invokeAsync(
+                        this.getCurrentVersion.bind(this),
+                        PerformanceEvents.RegionDiscoveryGetCurrentVersion,
+                        this.logger,
+                        this.performanceClient,
+                        this.correlationId
+                    )(options);
+                    if (!currentIMDSVersion) {
+                        regionDiscoveryMetadata.region_source =
+                            RegionDiscoverySources.FAILED_AUTO_DETECTION;
+                        return null;
+                    }
+
+                    const currentIMDSVersionResponse = await invokeAsync(
+                        this.getRegionFromIMDS.bind(this),
+                        PerformanceEvents.RegionDiscoveryGetRegionFromIMDS,
+                        this.logger,
+                        this.performanceClient,
+                        this.correlationId
+                    )(currentIMDSVersion, options);
+                    if (
+                        currentIMDSVersionResponse.status ===
+                        ResponseCodes.httpSuccess
+                    ) {
+                        autodetectedRegionName =
+                            currentIMDSVersionResponse.body;
+                        regionDiscoveryMetadata.region_source =
+                            RegionDiscoverySources.IMDS;
+                    }
+                }
+            } catch (e) {
+                regionDiscoveryMetadata.region_source =
+                    RegionDiscoverySources.FAILED_AUTO_DETECTION;
+                return null;
+            }
+        } else {
+            regionDiscoveryMetadata.region_source =
+                RegionDiscoverySources.ENVIRONMENT_VARIABLE;
+        }
+
+        // If no region was auto detected from the environment or from the IMDS endpoint, mark the attempt as a FAILED_AUTO_DETECTION
+        if (!autodetectedRegionName) {
+            regionDiscoveryMetadata.region_source =
+                RegionDiscoverySources.FAILED_AUTO_DETECTION;
+        }
+
+        return autodetectedRegionName || null;
+    }
+
+    /**
+     * Make the call to the IMDS endpoint
+     *
+     * @param imdsEndpointUrl
+     * @returns Promise<NetworkResponse<string>>
+     */
+    private async getRegionFromIMDS(
+        version: string,
+        options: ImdsOptions
+    ): Promise<NetworkResponse<string>> {
+        this.performanceClient?.addQueueMeasurement(
+            PerformanceEvents.RegionDiscoveryGetRegionFromIMDS,
+            this.correlationId
+        );
+        return this.networkInterface.sendGetRequestAsync<string>(
+            `${Constants.IMDS_ENDPOINT}?api-version=${version}&format=text`,
+            options,
+            Constants.IMDS_TIMEOUT
+        );
+    }
+
+    /**
+     * Get the most recent version of the IMDS endpoint available
+     *
+     * @returns Promise<string | null>
+     */
+    private async getCurrentVersion(
+        options: ImdsOptions
+    ): Promise<string | null> {
+        this.performanceClient?.addQueueMeasurement(
+            PerformanceEvents.RegionDiscoveryGetCurrentVersion,
+            this.correlationId
+        );
+        try {
+            const response =
+                await this.networkInterface.sendGetRequestAsync<IMDSBadResponse>(
+                    `${Constants.IMDS_ENDPOINT}?format=json`,
+                    options
+                );
+
+            // When IMDS endpoint is called without the api version query param, bad request response comes back with latest version.
+            if (
+                response.status === ResponseCodes.httpBadRequest &&
+                response.body &&
+                response.body["newest-versions"] &&
+                response.body["newest-versions"].length > 0
+            ) {
+                return response.body["newest-versions"][0];
+            }
+
+            return null;
+        } catch (e) {
+            return null;
+        }
+    }
+}

package/src/authority/RegionDiscoveryMetadata.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    RegionDiscoveryOutcomes,
+    RegionDiscoverySources,
+} from "../utils/Constants";
+
+export type RegionDiscoveryMetadata = {
+    region_used?: string;
+    region_source?: RegionDiscoverySources;
+    region_outcome?: RegionDiscoveryOutcomes;
+};

package/src/broker/nativeBroker/INativeBrokerPlugin.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AccountInfo } from "../../account/AccountInfo";
+import { LoggerOptions } from "../../config/ClientConfiguration";
+import { NativeRequest } from "../../request/NativeRequest";
+import { NativeSignOutRequest } from "../../request/NativeSignOutRequest";
+import { AuthenticationResult } from "../../response/AuthenticationResult";
+
+export interface INativeBrokerPlugin {
+    isBrokerAvailable: boolean;
+    setLogger(loggerOptions: LoggerOptions): void;
+    getAccountById(
+        accountId: string,
+        correlationId: string
+    ): Promise<AccountInfo>;
+    getAllAccounts(
+        clientId: string,
+        correlationId: string
+    ): Promise<AccountInfo[]>;
+    acquireTokenSilent(request: NativeRequest): Promise<AuthenticationResult>;
+    acquireTokenInteractive(
+        request: NativeRequest,
+        windowHandle?: Buffer
+    ): Promise<AuthenticationResult>;
+    signOut(request: NativeSignOutRequest): Promise<void>;
+}