[V5] Improved Managed Identity JSDocs (#8115)

Author: Robbie-Microsoft

change/@azure-msal-node-f8ac12ce-f9b6-4e88-b11a-8e5d388d1f92.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Improved Managed Identity JSDocs (#8115)",
+  "packageName": "@azure/msal-node",
+  "email": "rginsburg@microsoft.com",
+  "dependentChangeType": "patch"
+}

lib/msal-node/src/client/ManagedIdentitySources/AppService.ts

@@ -22,12 +22,29 @@ import { NodeStorage } from "../../cache/NodeStorage.js";
 const APP_SERVICE_MSI_API_VERSION: string = "2019-08-01";
 
 /**
+ * Azure App Service Managed Identity Source implementation.
+ *
+ * This class provides managed identity authentication for applications running in Azure App Service.
+ * It uses the local metadata service endpoint available within App Service environments to obtain
+ * access tokens without requiring explicit credentials.
+ *
  * Original source of code: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/src/AppServiceManagedIdentitySource.cs
  */
 export class AppService extends BaseManagedIdentitySource {
     private identityEndpoint: string;
     private identityHeader: string;
 
+    /**
+     * Creates a new instance of the AppService managed identity source.
+     *
+     * @param logger - Logger instance for diagnostic output
+     * @param nodeStorage - Node.js storage implementation for caching
+     * @param networkClient - Network client for making HTTP requests
+     * @param cryptoProvider - Cryptographic operations provider
+     * @param disableInternalRetries - Whether to disable internal retry logic
+     * @param identityEndpoint - The App Service identity endpoint URL
+     * @param identityHeader - The secret header value required for authentication
+     */
     constructor(
         logger: Logger,
         nodeStorage: NodeStorage,
@@ -49,6 +66,16 @@ export class AppService extends BaseManagedIdentitySource {
         this.identityHeader = identityHeader;
     }
 
+    /**
+     * Retrieves the required environment variables for App Service managed identity.
+     *
+     * App Service managed identity requires two environment variables:
+     * - IDENTITY_ENDPOINT: The URL of the local metadata service
+     * - IDENTITY_HEADER: A secret header value for authentication
+     *
+     * @returns An array containing [identityEndpoint, identityHeader] values from environment variables.
+     *          Either value may be undefined if the environment variable is not set.
+     */
     public static getEnvironmentVariables(): Array<string | undefined> {
         const identityEndpoint: string | undefined =
             process.env[
@@ -62,6 +89,21 @@ export class AppService extends BaseManagedIdentitySource {
         return [identityEndpoint, identityHeader];
     }
 
+    /**
+     * Attempts to create an AppService managed identity source if the environment supports it.
+     *
+     * This method checks for the presence of required environment variables and validates
+     * the identity endpoint URL. If the environment is not suitable for App Service managed
+     * identity (missing environment variables or invalid endpoint), it returns null.
+     *
+     * @param logger - Logger instance for diagnostic output
+     * @param nodeStorage - Node.js storage implementation for caching
+     * @param networkClient - Network client for making HTTP requests
+     * @param cryptoProvider - Cryptographic operations provider
+     * @param disableInternalRetries - Whether to disable internal retry logic
+     *
+     * @returns A new AppService instance if the environment is suitable, null otherwise
+     */
     public static tryCreate(
         logger: Logger,
         nodeStorage: NodeStorage,
@@ -105,6 +147,18 @@ export class AppService extends BaseManagedIdentitySource {
         );
     }
 
+    /**
+     * Creates a managed identity token request for the App Service environment.
+     *
+     * This method constructs an HTTP GET request to the App Service identity endpoint
+     * with the required headers, query parameters, and managed identity configuration.
+     * The request includes the secret header for authentication and appropriate API version.
+     *
+     * @param resource - The target resource/scope for which to request an access token (e.g., "https://graph.microsoft.com/.default")
+     * @param managedIdentityId - The managed identity configuration specifying whether to use system-assigned or user-assigned identity
+     *
+     * @returns A configured ManagedIdentityRequestParameters object ready for network execution
+     */
     public createRequest(
         resource: string,
         managedIdentityId: ManagedIdentityId

lib/msal-node/src/client/ManagedIdentitySources/AzureArc.ts

@@ -62,11 +62,27 @@ export const AZURE_ARC_FILE_DETECTION: FilePathMap = {
 };
 
 /**
+ * Azure Arc managed identity source implementation for acquiring tokens from Azure Arc-enabled servers.
+ *
+ * This class provides managed identity authentication for applications running on Azure Arc-enabled servers
+ * by communicating with the local Hybrid Instance Metadata Service (HIMDS). It supports both environment
+ * variable-based configuration and automatic detection through the HIMDS executable.
+ *
  * Original source of code: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/src/AzureArcManagedIdentitySource.cs
  */
 export class AzureArc extends BaseManagedIdentitySource {
     private identityEndpoint: string;
 
+    /**
+     * Creates a new instance of the AzureArc managed identity source.
+     *
+     * @param logger - Logger instance for capturing telemetry and diagnostic information
+     * @param nodeStorage - Storage implementation for caching tokens and metadata
+     * @param networkClient - Network client for making HTTP requests to the identity endpoint
+     * @param cryptoProvider - Cryptographic operations provider for token validation and encryption
+     * @param disableInternalRetries - Flag to disable automatic retry logic for failed requests
+     * @param identityEndpoint - The Azure Arc identity endpoint URL for token requests
+     */
     constructor(
         logger: Logger,
         nodeStorage: NodeStorage,
@@ -86,6 +102,17 @@ export class AzureArc extends BaseManagedIdentitySource {
         this.identityEndpoint = identityEndpoint;
     }
 
+    /**
+     * Retrieves and validates Azure Arc environment variables for managed identity configuration.
+     *
+     * This method checks for IDENTITY_ENDPOINT and IMDS_ENDPOINT environment variables.
+     * If either is missing, it attempts to detect the Azure Arc environment by checking for
+     * the HIMDS executable at platform-specific paths. On successful detection, it returns
+     * the default identity endpoint and a helper string indicating file-based detection.
+     *
+     * @returns An array containing [identityEndpoint, imdsEndpoint] where both values are
+     *          strings if Azure Arc is available, or undefined if not available.
+     */
     public static getEnvironmentVariables(): Array<string | undefined> {
         let identityEndpoint: string | undefined =
             process.env[
@@ -122,6 +149,25 @@ export class AzureArc extends BaseManagedIdentitySource {
         return [identityEndpoint, imdsEndpoint];
     }
 
+    /**
+     * Attempts to create an AzureArc managed identity source instance.
+     *
+     * Validates the Azure Arc environment by checking environment variables
+     * and performing file-based detection. It ensures that only system-assigned managed identities
+     * are supported for Azure Arc scenarios. The method performs comprehensive validation of
+     * endpoint URLs and logs detailed information about the detection process.
+     *
+     * @param logger - Logger instance for capturing creation and validation steps
+     * @param nodeStorage - Storage implementation for the managed identity source
+     * @param networkClient - Network client for HTTP communication
+     * @param cryptoProvider - Cryptographic operations provider
+     * @param disableInternalRetries - Whether to disable automatic retry mechanisms
+     * @param managedIdentityId - The managed identity configuration, must be system-assigned
+     *
+     * @returns AzureArc instance if the environment supports Azure Arc managed identity, null otherwise
+     *
+     * @throws {ManagedIdentityError} When a user-assigned managed identity is specified (not supported for Azure Arc)
+     */
     public static tryCreate(
         logger: Logger,
         nodeStorage: NodeStorage,
@@ -195,6 +241,17 @@ export class AzureArc extends BaseManagedIdentitySource {
         );
     }
 
+    /**
+     * Creates a properly formatted HTTP request for acquiring tokens from the Azure Arc identity endpoint.
+     *
+     * This method constructs a GET request to the Azure Arc HIMDS endpoint with the required metadata header
+     * and query parameters. The endpoint URL is normalized to use 127.0.0.1 instead of localhost for
+     * consistency. Additional body parameters are calculated by the base class during token acquisition.
+     *
+     * @param resource - The target resource/scope for which to request an access token (e.g., "https://graph.microsoft.com/.default")
+     *
+     * @returns A configured ManagedIdentityRequestParameters object ready for network execution
+     */
     public createRequest(resource: string): ManagedIdentityRequestParameters {
         const request: ManagedIdentityRequestParameters =
             new ManagedIdentityRequestParameters(
@@ -214,6 +271,30 @@ export class AzureArc extends BaseManagedIdentitySource {
         return request;
     }
 
+    /**
+     * Processes the server response and handles Azure Arc-specific authentication challenges.
+     *
+     * This method implements the Azure Arc authentication flow which may require reading a secret file
+     * for authorization. When the initial request returns HTTP 401 Unauthorized, it extracts the file
+     * path from the WWW-Authenticate header, validates the file location and size, reads the secret,
+     * and retries the request with Basic authentication. The method includes comprehensive security
+     * validations to prevent path traversal and ensure file integrity.
+     *
+     * @param originalResponse - The initial HTTP response from the identity endpoint
+     * @param networkClient - Network client for making the retry request if needed
+     * @param networkRequest - The original request parameters (modified with auth header for retry)
+     * @param networkRequestOptions - Additional options for network requests
+     *
+     * @returns A promise that resolves to the server token response with access token and metadata
+     *
+     * @throws {ManagedIdentityError} When:
+     *   - WWW-Authenticate header is missing or has unsupported format
+     *   - Platform is not supported (not Windows or Linux)
+     *   - Secret file has invalid extension (not .key)
+     *   - Secret file path doesn't match expected platform path
+     *   - Secret file cannot be read or is too large (>4096 bytes)
+     * @throws {ClientAuthError} When network errors occur during retry request
+     */
     public async getServerTokenResponseAsync(
         originalResponse: NetworkResponse<ManagedIdentityTokenResponse>,
         networkClient: INetworkModule,

lib/msal-node/src/client/ManagedIdentitySources/BaseManagedIdentitySource.ts

@@ -51,13 +51,30 @@ export const ManagedIdentityUserAssignedIdQueryParameterNames = {
 export type ManagedIdentityUserAssignedIdQueryParameterNames =
     (typeof ManagedIdentityUserAssignedIdQueryParameterNames)[keyof typeof ManagedIdentityUserAssignedIdQueryParameterNames];
 
+/**
+ * Base class for all Managed Identity sources. Provides common functionality for
+ * authenticating with Azure Managed Identity endpoints across different Azure services
+ * including IMDS, App Service, Azure Arc, Service Fabric, Cloud Shell, and Machine Learning.
+ *
+ * This abstract class handles token acquisition, response processing, and network communication
+ * while allowing concrete implementations to define source-specific request creation logic.
+ */
 export abstract class BaseManagedIdentitySource {
     protected logger: Logger;
     private nodeStorage: NodeStorage;
     private networkClient: INetworkModule;
     private cryptoProvider: CryptoProvider;
     private disableInternalRetries: boolean;
 
+    /**
+     * Creates an instance of BaseManagedIdentitySource.
+     *
+     * @param logger - Logger instance for diagnostic information
+     * @param nodeStorage - Storage interface for caching tokens
+     * @param networkClient - Network client for making HTTP requests
+     * @param cryptoProvider - Cryptographic provider for token operations
+     * @param disableInternalRetries - Whether to disable automatic retry logic
+     */
     constructor(
         logger: Logger,
         nodeStorage: NodeStorage,
@@ -72,11 +89,33 @@ export abstract class BaseManagedIdentitySource {
         this.disableInternalRetries = disableInternalRetries;
     }
 
+    /**
+     * Creates a managed identity request with source-specific parameters.
+     * This method must be implemented by concrete managed identity sources to define
+     * how requests are constructed for their specific endpoint requirements.
+     *
+     * @param resource - The Azure resource URI for which the access token is requested (e.g., "https://vault.azure.net/")
+     * @param managedIdentityId - The managed identity configuration specifying system-assigned or user-assigned identity details
+     *
+     * @returns Request parameters configured for the specific managed identity source
+     */
     abstract createRequest(
-        request: string,
+        resource: string,
         managedIdentityId: ManagedIdentityId
     ): ManagedIdentityRequestParameters;
 
+    /**
+     * Processes the network response and converts it to a standardized server token response.
+     * This async version allows for source-specific response processing logic while maintaining
+     * backward compatibility with the synchronous version.
+     *
+     * @param response - The network response containing the managed identity token
+     * @param _networkClient - Network client used for the request (unused in base implementation)
+     * @param _networkRequest - The original network request parameters (unused in base implementation)
+     * @param _networkRequestOptions - The network request options (unused in base implementation)
+     *
+     * @returns Promise resolving to a standardized server authorization token response
+     */
     public async getServerTokenResponseAsync(
         response: NetworkResponse<ManagedIdentityTokenResponse>,
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -89,6 +128,15 @@ export abstract class BaseManagedIdentitySource {
         return this.getServerTokenResponse(response);
     }
 
+    /**
+     * Converts a managed identity token response to a standardized server authorization token response.
+     * Handles time format conversion, expiration calculation, and error mapping to ensure
+     * compatibility with the MSAL response handling pipeline.
+     *
+     * @param response - The network response containing the managed identity token
+     *
+     * @returns Standardized server authorization token response with normalized fields
+     */
     public getServerTokenResponse(
         response: NetworkResponse<ManagedIdentityTokenResponse>
     ): ServerAuthorizationTokenResponse {
@@ -138,6 +186,21 @@ export abstract class BaseManagedIdentitySource {
         return serverTokenResponse;
     }
 
+    /**
+     * Acquires an access token using the managed identity endpoint for the specified resource.
+     * This is the primary method for token acquisition, handling the complete flow from
+     * request creation through response processing and token caching.
+     *
+     * @param managedIdentityRequest - The managed identity request containing resource and optional parameters
+     * @param managedIdentityId - The managed identity configuration (system or user-assigned)
+     * @param fakeAuthority - Authority instance used for token caching (managed identity uses a placeholder authority)
+     * @param refreshAccessToken - Whether this is a token refresh operation
+     *
+     * @returns Promise resolving to an authentication result containing the access token and metadata
+     *
+     * @throws {AuthError} When network requests fail or token validation fails
+     * @throws {ClientAuthError} When network errors occur during the request
+     */
     public async acquireTokenWithManagedIdentity(
         managedIdentityRequest: ManagedIdentityRequest,
         managedIdentityId: ManagedIdentityId,
@@ -258,6 +321,19 @@ export abstract class BaseManagedIdentitySource {
         );
     }
 
+    /**
+     * Determines the appropriate query parameter name for user-assigned managed identity
+     * based on the identity type, API version, and endpoint characteristics.
+     * Different Azure services and API versions use different parameter names for the same identity types.
+     *
+     * @param managedIdentityIdType - The type of user-assigned managed identity (client ID, object ID, or resource ID)
+     * @param isImds - Whether the request is being made to the IMDS (Instance Metadata Service) endpoint
+     * @param usesApi2017 - Whether the endpoint uses the 2017-09-01 API version (affects client ID parameter name)
+     *
+     * @returns The correct query parameter name for the specified identity type and endpoint
+     *
+     * @throws {ManagedIdentityError} When an invalid managed identity ID type is provided
+     */
     public getManagedIdentityUserAssignedIdQueryParameterKey(
         managedIdentityIdType: ManagedIdentityIdType,
         isImds?: boolean,
@@ -298,6 +374,20 @@ export abstract class BaseManagedIdentitySource {
         }
     }
 
+    /**
+     * Validates and normalizes an environment variable containing a URL string.
+     * This static utility method ensures that environment variables used for managed identity
+     * endpoints contain properly formatted URLs and provides informative error messages when validation fails.
+     *
+     * @param envVariableStringName - The name of the environment variable being validated (for error reporting)
+     * @param envVariable - The environment variable value containing the URL string
+     * @param sourceName - The name of the managed identity source (for error reporting)
+     * @param logger - Logger instance for diagnostic information
+     *
+     * @returns The validated and normalized URL string
+     *
+     * @throws {ManagedIdentityError} When the environment variable contains a malformed URL
+     */
     public static getValidatedEnvVariableUrlString = (
         envVariableStringName: keyof typeof ManagedIdentityErrorCodes.MsiEnvironmentVariableUrlMalformedErrorCodes,
         envVariable: string,