[msal-node]: Add regional authorities telemetry

change/@azure-msal-angular-93820d74-8077-45d4-b5fe-abbc1173a1b1.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: fixing the npm audit issues",
+  "packageName": "@azure/msal-angular",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-browser-e02e76bb-e3be-4942-92fb-db7f87c51270.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: fixing the npm audit issues",
+  "packageName": "@azure/msal-browser",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-3150477f-929f-4013-8176-77b1a63f8912.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add regional authority telemetry #3662",
+  "packageName": "@azure/msal-common",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-extensions-775467ab-ea19-4849-9a64-291a495d4226.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: bump up the msal-common version",
+  "packageName": "@azure/msal-node-extensions",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-f63abd0d-4eab-4485-ba86-ca75799c6065.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add regional authority telemetry, #3662",
+  "packageName": "@azure/msal-node",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-react-c60f303b-d77c-45c3-80f1-0012a472df94.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: fixing the npm audit issues",
+  "packageName": "@azure/msal-react",
+  "email": "samuelkamau@microsoft.com",
+  "dependentChangeType": "patch"
+}

lib/msal-common/src/authority/Authority.ts

@@ -9,7 +9,7 @@ import { UrlString } from "../url/UrlString";
 import { IUri } from "../url/IUri";
 import { ClientAuthError } from "../error/ClientAuthError";
 import { INetworkModule } from "../network/INetworkModule";
-import { AuthorityMetadataSource, Constants } from "../utils/Constants";
+import { AuthorityMetadataSource, Constants, RegionDiscoveryOutcomes } from "../utils/Constants";
 import { ClientConfigurationError } from "../error/ClientConfigurationError";
 import { ProtocolMode } from "./ProtocolMode";
 import { ICacheManager } from "../cache/interface/ICacheManager";
@@ -18,6 +18,7 @@ import { AuthorityOptions } from "./AuthorityOptions";
 import { CloudInstanceDiscoveryResponse, isCloudInstanceDiscoveryResponse } from "./CloudInstanceDiscoveryResponse";
 import { CloudDiscoveryMetadata } from "./CloudDiscoveryMetadata";
 import { RegionDiscovery } from "./RegionDiscovery";
+import { RegionDiscoveryMetadata } from "./RegionDiscoveryMetadata";
 
 /**
  * The authority class validates the authority URIs used by the user, and retrieves the OpenID Configuration Data from the
@@ -39,6 +40,8 @@ export class Authority {
     private metadata: AuthorityMetadataEntity;
     // Region discovery service
     private regionDiscovery: RegionDiscovery;
+    // Region discovery metadata
+    public regionDiscoveryMetadata: RegionDiscoveryMetadata;
 
     constructor(authority: string, networkInterface: INetworkModule, cacheManager: ICacheManager, authorityOptions: AuthorityOptions) {
         this.canonicalAuthority = authority;
@@ -47,6 +50,7 @@ export class Authority {
         this.cacheManager = cacheManager;
         this.authorityOptions = authorityOptions;
         this.regionDiscovery = new RegionDiscovery(networkInterface);
+        this.regionDiscoveryMetadata = { region_used: undefined, region_source: undefined, region_outcome: undefined };
     }
 
     // See above for AuthorityType
@@ -263,13 +267,28 @@ export class Authority {
         if (metadata) {
             // If the user prefers to use an azure region replace the global endpoints with regional information.
             if (this.authorityOptions.azureRegionConfiguration?.azureRegion) {
-                const autodetectedRegionName = await this.regionDiscovery.detectRegion(this.authorityOptions.azureRegionConfiguration.environmentRegion);
+                const autodetectedRegionName = await this.regionDiscovery.detectRegion(this.authorityOptions.azureRegionConfiguration.environmentRegion, this.regionDiscoveryMetadata);
 
                 const azureRegion = this.authorityOptions.azureRegionConfiguration.azureRegion === Constants.AZURE_REGION_AUTO_DISCOVER_FLAG 
                     ? autodetectedRegionName 
                     : this.authorityOptions.azureRegionConfiguration.azureRegion;
 
+                if (this.authorityOptions.azureRegionConfiguration.azureRegion === Constants.AZURE_REGION_AUTO_DISCOVER_FLAG) {
+                    this.regionDiscoveryMetadata.region_outcome = autodetectedRegionName ?
+                        RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_SUCCESSFUL :
+                        RegionDiscoveryOutcomes.AUTO_DETECTION_REQUESTED_FAILED;
+                } else {
+                    if (autodetectedRegionName) {
+                        this.regionDiscoveryMetadata.region_outcome = (this.authorityOptions.azureRegionConfiguration.azureRegion === autodetectedRegionName) ?
+                            RegionDiscoveryOutcomes.CONFIGURED_MATCHES_DETECTED :
+                            RegionDiscoveryOutcomes.CONFIGURED_NOT_DETECTED;
+                    } else {
+                        this.regionDiscoveryMetadata.region_outcome = RegionDiscoveryOutcomes.CONFIGURED_NO_AUTO_DETECTION;
+                    }
+                }
+
                 if (azureRegion) {
+                    this.regionDiscoveryMetadata.region_used = azureRegion;
                     metadata = Authority.replaceWithRegionalInformation(metadata, azureRegion);
                 }
             }

lib/msal-common/src/authority/RegionDiscovery.ts

@@ -6,7 +6,8 @@
 import { INetworkModule } from "../network/INetworkModule";
 import { NetworkResponse } from "../network/NetworkManager";
 import { IMDSBadResponse } from "../response/IMDSBadResponse";
-import { Constants, ResponseCodes } from "../utils/Constants";
+import { Constants, RegionDiscoverySources, ResponseCodes } from "../utils/Constants";
+import { RegionDiscoveryMetadata } from "./RegionDiscoveryMetadata";
 
 export class RegionDiscovery {
     // Network interface to make requests with.
@@ -23,7 +24,7 @@ export class RegionDiscovery {
      * 
      * @returns Promise<string | null>
      */
-    public async detectRegion(environmentRegion: string | undefined): Promise<string | null> {
+    public async detectRegion(environmentRegion: string | undefined, regionDiscoveryMetadata: RegionDiscoveryMetadata): Promise<string | null> {
         // Initialize auto detected region with the region from the envrionment 
         let autodetectedRegionName = environmentRegion;
 
@@ -38,19 +39,27 @@ export class RegionDiscovery {
                 if (response.status === ResponseCodes.httpBadRequest) {
                     const latestIMDSVersion = await this.getCurrentVersion();
                     if (!latestIMDSVersion) {
+                        regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
                         return null;
                     }
 
                     const response = await this.getRegionFromIMDS(latestIMDSVersion);
                     if (response.status === ResponseCodes.httpSuccess) {
                         autodetectedRegionName = response.body;
                     }
-                } 
+                }
+
+                if (autodetectedRegionName) regionDiscoveryMetadata.region_source = RegionDiscoverySources.IMDS;
             } catch(e) {
+                regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
                 return null;
             } 
+        } else {
+            regionDiscoveryMetadata.region_source = RegionDiscoverySources.ENVIRONMENT_VARIABLE;
         }
 
+        if (!autodetectedRegionName) regionDiscoveryMetadata.region_source = RegionDiscoverySources.FAILED_AUTO_DETECTION;
+
         return autodetectedRegionName || null;
     }
 

lib/msal-common/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;
+};

lib/msal-common/src/client/ClientCredentialClient.ts

@@ -8,7 +8,7 @@ import { BaseClient } from "./BaseClient";
 import { Authority } from "../authority/Authority";
 import { RequestParameterBuilder } from "../request/RequestParameterBuilder";
 import { ScopeSet } from "../request/ScopeSet";
-import { GrantType , CredentialType } from "../utils/Constants";
+import { GrantType , CredentialType, CacheOutcome } from "../utils/Constants";
 import { ResponseHandler } from "../response/ResponseHandler";
 import { AuthenticationResult } from "../response/AuthenticationResult";
 import { CommonClientCredentialRequest } from "../request/CommonClientCredentialRequest";
@@ -54,9 +54,16 @@ export class ClientCredentialClient extends BaseClient {
      * looks up cache if the tokens are cached already
      */
     private async getCachedAuthenticationResult(request: CommonClientCredentialRequest): Promise<AuthenticationResult | null> {
+
         const cachedAccessToken = this.readAccessTokenFromCache();
-        if (!cachedAccessToken ||
-            TimeUtils.isTokenExpired(cachedAccessToken.expiresOn, this.config.systemOptions.tokenRenewalOffsetSeconds)) {
+
+        if (!cachedAccessToken) {
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.NO_CACHED_ACCESS_TOKEN);
+            return null;
+        }
+
+        if (TimeUtils.isTokenExpired(cachedAccessToken.expiresOn, this.config.systemOptions.tokenRenewalOffsetSeconds)) {
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED);
             return null;
         }
 

lib/msal-common/src/client/OnBehalfOfClient.ts

@@ -8,7 +8,7 @@ import { BaseClient } from "./BaseClient";
 import { Authority } from "../authority/Authority";
 import { RequestParameterBuilder } from "../request/RequestParameterBuilder";
 import { ScopeSet } from "../request/ScopeSet";
-import { GrantType, AADServerParamKeys , CredentialType, Constants } from "../utils/Constants";
+import { GrantType, AADServerParamKeys , CredentialType, Constants, CacheOutcome } from "../utils/Constants";
 import { ResponseHandler } from "../response/ResponseHandler";
 import { AuthenticationResult } from "../response/AuthenticationResult";
 import { CommonOnBehalfOfRequest } from "../request/CommonOnBehalfOfRequest";
@@ -60,6 +60,10 @@ export class OnBehalfOfClient extends BaseClient {
         const cachedAccessToken = this.readAccessTokenFromCache();
         if (!cachedAccessToken ||
             TimeUtils.isTokenExpired(cachedAccessToken.expiresOn, this.config.systemOptions.tokenRenewalOffsetSeconds)) {
+
+            // Update the server telemetry outcome
+            this.serverTelemetryManager?.setCacheOutcome(!cachedAccessToken ? CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED : CacheOutcome.NO_CACHED_ACCESS_TOKEN);
+
             return null;
         }
 

lib/msal-common/src/client/SilentFlowClient.ts

@@ -15,7 +15,7 @@ import { ClientAuthError, ClientAuthErrorMessage } from "../error/ClientAuthErro
 import { ClientConfigurationError } from "../error/ClientConfigurationError";
 import { ResponseHandler } from "../response/ResponseHandler";
 import { CacheRecord } from "../cache/entities/CacheRecord";
-import { AuthenticationScheme } from "../utils/Constants";
+import { AuthenticationScheme, CacheOutcome } from "../utils/Constants";
 import { StringUtils } from "../utils/StringUtils";
 
 export class SilentFlowClient extends BaseClient {
@@ -60,14 +60,28 @@ export class SilentFlowClient extends BaseClient {
         const environment = request.authority || this.authority.getPreferredCache();
         const authScheme = request.authenticationScheme || AuthenticationScheme.BEARER;
         const cacheRecord = this.cacheManager.readCacheRecord(request.account, this.config.authOptions.clientId, requestScopes, environment, authScheme);
-
-        if (request.forceRefresh || 
-            !StringUtils.isEmptyObj(request.claims) || 
-            !cacheRecord.accessToken || 
-            TimeUtils.isTokenExpired(cacheRecord.accessToken.expiresOn, this.config.systemOptions.tokenRenewalOffsetSeconds) ||
+
+        if (request.forceRefresh) {
+            // Must refresh due to present force_refresh flag.
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.FORCE_REFRESH);
+            throw ClientAuthError.createRefreshRequiredError();
+        } else if (!cacheRecord.accessToken) {
+            // Must refresh due to non-existent access_token.
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.NO_CACHED_ACCESS_TOKEN);
+            throw ClientAuthError.createRefreshRequiredError();
+        } else if (
             TimeUtils.wasClockTurnedBack(cacheRecord.accessToken.cachedAt) ||
-            (cacheRecord.accessToken.refreshOn && TimeUtils.isTokenExpired(cacheRecord.accessToken.refreshOn, 0))) {
-            // Must refresh due to request parameters, or expired or non-existent access_token
+            TimeUtils.isTokenExpired(cacheRecord.accessToken.expiresOn, this.config.systemOptions.tokenRenewalOffsetSeconds)
+        ) {
+            // Must refresh due to expired access_token.
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED);
+            throw ClientAuthError.createRefreshRequiredError();
+        } else if (cacheRecord.accessToken.refreshOn && TimeUtils.isTokenExpired(cacheRecord.accessToken.refreshOn, 0)) {
+            // Must refresh due to the refresh_in value.
+            this.serverTelemetryManager?.setCacheOutcome(CacheOutcome.REFRESH_CACHED_ACCESS_TOKEN);
+            throw ClientAuthError.createRefreshRequiredError();
+        } else if (!StringUtils.isEmptyObj(request.claims)) {
+            // Must refresh due to request parameters.
             throw ClientAuthError.createRefreshRequiredError();
         }
 

lib/msal-common/src/telemetry/server/ServerTelemetryManager.ts

@@ -3,27 +3,30 @@
  * Licensed under the MIT License.
  */
 
-import { SERVER_TELEM_CONSTANTS, Separators, Constants } from "../../utils/Constants";
+import { SERVER_TELEM_CONSTANTS, Separators, CacheOutcome, Constants, RegionDiscoverySources, RegionDiscoveryOutcomes } from "../../utils/Constants";
 import { CacheManager } from "../../cache/CacheManager";
 import { AuthError } from "../../error/AuthError";
 import { ServerTelemetryRequest } from "./ServerTelemetryRequest";
 import { ServerTelemetryEntity } from "../../cache/entities/ServerTelemetryEntity";
 import { StringUtils } from "../../utils/StringUtils";
+import { RegionDiscoveryMetadata } from "../../authority/RegionDiscoveryMetadata";
 
 export class ServerTelemetryManager {
     private cacheManager: CacheManager;
     private apiId: number;
     private correlationId: string;
-    private forceRefresh: boolean;
     private telemetryCacheKey: string;
     private wrapperSKU: String;
     private wrapperVer: String;
+    private regionUsed: string | undefined;
+    private regionSource: RegionDiscoverySources | undefined;
+    private regionOutcome: RegionDiscoveryOutcomes | undefined;
+    private cacheOutcome: CacheOutcome = CacheOutcome.NO_CACHE_HIT;
 
     constructor(telemetryRequest: ServerTelemetryRequest, cacheManager: CacheManager) {
         this.cacheManager = cacheManager;
         this.apiId = telemetryRequest.apiId;
         this.correlationId = telemetryRequest.correlationId;
-        this.forceRefresh = telemetryRequest.forceRefresh || false;
         this.wrapperSKU = telemetryRequest.wrapperSKU || Constants.EMPTY_STRING;
         this.wrapperVer = telemetryRequest.wrapperVer || Constants.EMPTY_STRING;
 
@@ -34,11 +37,12 @@ export class ServerTelemetryManager {
      * API to add MSER Telemetry to request
      */
     generateCurrentRequestHeaderValue(): string {
-        const forceRefreshInt = this.forceRefresh ? 1 : 0;
-        const request = `${this.apiId}${SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR}${forceRefreshInt}`;
+        const request = `${this.apiId}${SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR}${this.cacheOutcome}`;
         const platformFields = [this.wrapperSKU, this.wrapperVer].join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
+        const regionDiscoveryFields = this.getRegionDiscoveryFields();
+        const requestWithRegionDiscoveryFields = [request, regionDiscoveryFields].join(SERVER_TELEM_CONSTANTS.VALUE_SEPARATOR);
 
-        return [SERVER_TELEM_CONSTANTS.SCHEMA_VERSION, request, platformFields].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
+        return [SERVER_TELEM_CONSTANTS.SCHEMA_VERSION, requestWithRegionDiscoveryFields, platformFields].join(SERVER_TELEM_CONSTANTS.CATEGORY_SEPARATOR);
     }
 
     /**
@@ -158,4 +162,38 @@ export class ServerTelemetryManager {
 
         return maxErrors;
     }
+
+    /**
+     * Get the region discovery fields
+     * 
+     * @returns string
+     */
+    getRegionDiscoveryFields(): string {
+        const regionDiscoveryFields: string[] = [];
+
+        regionDiscoveryFields.push(this.regionUsed || "");
+        regionDiscoveryFields.push(this.regionSource || "");
+        regionDiscoveryFields.push(this.regionOutcome || "");
+
+        return regionDiscoveryFields.join(",");
+    }
+
+    /**
+     * Update the region discovery metadata
+     * 
+     * @param regionDiscoveryMetadata
+     * @returns void
+     */
+    updateRegionDiscoveryMetadata(regionDiscoveryMetadata: RegionDiscoveryMetadata): void {
+        this.regionUsed = regionDiscoveryMetadata.region_used;
+        this.regionSource = regionDiscoveryMetadata.region_source;
+        this.regionOutcome = regionDiscoveryMetadata.region_outcome;
+    }
+
+    /**
+     * Set cache outcome 
+     */
+    setCacheOutcome(cacheOutcome: CacheOutcome): void {
+        this.cacheOutcome = cacheOutcome;
+    }
 }

lib/msal-common/src/utils/Constants.ts

@@ -299,7 +299,7 @@ export enum AuthorityMetadataSource {
 }
 
 export const SERVER_TELEM_CONSTANTS = {
-    SCHEMA_VERSION: 2,
+    SCHEMA_VERSION: 5,
     MAX_CUR_HEADER_BYTES: 80, // ESTS limit is 100B, set to 80 to provide a 20B buffer
     MAX_LAST_HEADER_BYTES: 330, // ESTS limit is 350B, set to 330 to provide a 20B buffer,
     MAX_CACHED_ERRORS: 50, // Limit the number of errors that can be stored to prevent uncontrolled size gains
@@ -353,3 +353,32 @@ export enum  ResponseCodes {
     httpSuccess = 200,
     httpBadRequest = 400
 }
+
+/**
+ * Region Discovery Sources
+ */
+export enum RegionDiscoverySources {
+    FAILED_AUTO_DETECTION = "1",
+    INTERNAL_CACHE = "2",
+    ENVIRONMENT_VARIABLE = "3",
+    IMDS = "4",
+}
+
+/**
+ * Region Discovery Outcomes
+ */
+export enum RegionDiscoveryOutcomes {
+    CONFIGURED_MATCHES_DETECTED = "1",
+    CONFIGURED_NO_AUTO_DETECTION = "2",
+    CONFIGURED_NOT_DETECTED = "3",
+    AUTO_DETECTION_REQUESTED_SUCCESSFUL = "4",
+    AUTO_DETECTION_REQUESTED_FAILED = "5"
+}
+
+export enum CacheOutcome {
+    NO_CACHE_HIT = "0",
+    FORCE_REFRESH = "1",
+    NO_CACHED_ACCESS_TOKEN = "2",
+    CACHED_ACCESS_TOKEN_EXPIRED = "3",
+    REFRESH_CACHED_ACCESS_TOKEN = "4"
+}