Merge pull request #5578 from AzureAD/custom-loopback-client

Allow adding custom loopback client in acquireTokenInteractive

Author: Doğan Erişen

change/@azure-msal-node-a8c6ab7d-514e-4bf2-b17a-42bb0cdb5a22.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Allow adding custom loopback client in acquireTokenInteractive #5578",
+  "packageName": "@azure/msal-node",
+  "email": "v-derisen@microsoft.com",
+  "dependentChangeType": "minor"
+}

lib/msal-node/src/client/PublicClientApplication.ts

@@ -24,6 +24,7 @@ import { AuthorizationCodeRequest } from "../request/AuthorizationCodeRequest";
 import { InteractiveRequest } from "../request/InteractiveRequest";
 import { NodeAuthError } from "../error/NodeAuthError";
 import { LoopbackClient } from "../network/LoopbackClient";
+import { ILoopbackClient } from "../network/ILoopbackClient";
 
 /**
  * This class is to be used to acquire tokens for public client applications (desktop, mobile). Public client applications
@@ -86,13 +87,14 @@ export class PublicClientApplication extends ClientApplication implements IPubli
     }
 
     /**
-     * Acquires a token by requesting an Authorization code then exchanging it for a token.
+     * Acquires a token interactively via the browser by requesting an authorization code then exchanging it for a token.
      */
-    async acquireTokenInteractive(request: InteractiveRequest): Promise<AuthenticationResult> {
+    public async acquireTokenInteractive(request: InteractiveRequest): Promise<AuthenticationResult> {
         const { verifier, challenge } = await this.cryptoProvider.generatePkceCodes();
-        const { openBrowser, successTemplate, errorTemplate, ...remainingProperties } = request;
+        const { openBrowser, successTemplate, errorTemplate, loopbackClient: customLoopbackClient, ...remainingProperties } = request;
+
+        const loopbackClient: ILoopbackClient = customLoopbackClient || new LoopbackClient();
 
-        const loopbackClient = new LoopbackClient();
         const authCodeListener = loopbackClient.listenForAuthCode(successTemplate, errorTemplate);
         const redirectUri = loopbackClient.getRedirectUri();
 
@@ -101,7 +103,7 @@ export class PublicClientApplication extends ClientApplication implements IPubli
             scopes: request.scopes || OIDC_DEFAULT_SCOPES,
             redirectUri: redirectUri,
             responseMode: ResponseMode.QUERY,
-            codeChallenge: challenge, 
+            codeChallenge: challenge,
             codeChallengeMethod: CodeChallengeMethodValues.S256
         };
 

lib/msal-node/src/index.ts

@@ -14,6 +14,7 @@ export { IConfidentialClientApplication } from "./client/IConfidentialClientAppl
 export { ITokenCache } from "./cache/ITokenCache";
 export { ICacheClient } from "./cache/distributed/ICacheClient";
 export { IPartitionManager } from "./cache/distributed/IPartitionManager";
+export { ILoopbackClient } from "./network/ILoopbackClient";
 
 // Clients and Configuration
 export { PublicClientApplication } from "./client/PublicClientApplication";

lib/msal-node/src/network/ILoopbackClient.ts

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ServerAuthorizationCodeResponse } from "@azure/msal-common";
+
+/**
+ * Interface for LoopbackClient allowing to replace the default loopback server with a custom implementation.
+ * @public
+ */
+export interface ILoopbackClient {
+    listenForAuthCode(successTemplate?: string, errorTemplate?: string): Promise<ServerAuthorizationCodeResponse>,
+    getRedirectUri(): string,
+    closeServer(): void
+}

lib/msal-node/src/network/LoopbackClient.ts

@@ -7,15 +7,16 @@ import { Constants as CommonConstants, ServerAuthorizationCodeResponse, UrlStrin
 import { createServer, IncomingMessage, Server, ServerResponse } from "http";
 import { NodeAuthError } from "../error/NodeAuthError";
 import { Constants, HttpStatus, LOOPBACK_SERVER_CONSTANTS } from "../utils/Constants";
+import { ILoopbackClient } from "./ILoopbackClient";
 
-export class LoopbackClient {
+export class LoopbackClient implements ILoopbackClient {
     private server: Server;
 
     /**
      * Spins up a loopback server which returns the server response when the localhost redirectUri is hit
-     * @param successTemplate 
-     * @param errorTemplate 
-     * @returns 
+     * @param successTemplate
+     * @param errorTemplate
+     * @returns
      */
     async listenForAuthCode(successTemplate?: string, errorTemplate?: string): Promise<ServerAuthorizationCodeResponse> {
         if (!!this.server) {
@@ -33,7 +34,7 @@ export class LoopbackClient {
                     res.end(successTemplate || "Auth code was successfully acquired. You can close this window now.");
                     return;
                 }
-    
+
                 const authCodeResponse = UrlString.getDeserializedQueryString(url);
                 if (authCodeResponse.code) {
                     const redirectUri = await this.getRedirectUri();
@@ -52,7 +53,7 @@ export class LoopbackClient {
                 if ((LOOPBACK_SERVER_CONSTANTS.TIMEOUT_MS / LOOPBACK_SERVER_CONSTANTS.INTERVAL_MS) < ticks) {
                     throw NodeAuthError.createLoopbackServerTimeoutError();
                 }
-                
+
                 if (this.server.listening) {
                     clearInterval(id);
                     resolve();
@@ -66,18 +67,18 @@ export class LoopbackClient {
 
     /**
      * Get the port that the loopback server is running on
-     * @returns 
+     * @returns
      */
     getRedirectUri(): string {
         if (!this.server) {
             throw NodeAuthError.createNoLoopbackServerExistsError();
         }
-                
+
         const address = this.server.address();
         if (!address || typeof address === "string" || !address.port) {
             this.closeServer();
             throw NodeAuthError.createInvalidLoopbackAddressTypeError();
-        } 
+        }
 
         const port = address && address.port;
 

lib/msal-node/src/request/InteractiveRequest.ts

@@ -3,11 +3,23 @@
  * Licensed under the MIT License.
  */
 
+import { ILoopbackClient } from "../network/ILoopbackClient";
 import { AuthorizationUrlRequest } from "./AuthorizationUrlRequest";
 
+/**
+ * Request object passed by user to configure acquireTokenInteractive API
+ *
+ * - openBrowser             - Function to open a browser instance on user's system.
+ * - scopes                  - Array of scopes the application is requesting access to.
+ * - successTemplate:        - Template to be displayed on the opened browser instance upon successful token acquisition.
+ * - errorTemplate           - Template to be displayed on the opened browser instance upon token acquisition failure.
+ * - loopbackClient          - Custom implementation for a loopback server to listen for authorization code response.
+ * @public
+ */
 export type InteractiveRequest = Pick<AuthorizationUrlRequest, "authority"|"correlationId"|"claims"|"azureCloudOptions"|"account"|"extraQueryParameters"|"tokenQueryParameters"|"extraScopesToConsent"|"loginHint"|"prompt"> & {
     openBrowser: (url: string) => Promise<void>;
     scopes?: Array<string>;
     successTemplate?: string;
     errorTemplate?: string;
+    loopbackClient?: ILoopbackClient
 };

lib/msal-node/test/client/PublicClientApplication.spec.ts

@@ -1,9 +1,9 @@
 import { PublicClientApplication } from './../../src/client/PublicClientApplication';
-import { Configuration, InteractiveRequest } from './../../src/index';
-import { ID_TOKEN_CLAIMS, mockAuthenticationResult, TEST_CONSTANTS } from '../utils/TestConstants';
+import { Configuration, ILoopbackClient, InteractiveRequest } from './../../src/index';
+import { ID_TOKEN_CLAIMS, mockAuthenticationResult, TEST_CONSTANTS, TEST_DATA_CLIENT_INFO } from '../utils/TestConstants';
 import {
     ClientConfiguration, AuthenticationResult, AuthorizationCodeClient, RefreshTokenClient, UsernamePasswordClient,
-    SilentFlowClient, ProtocolMode, Logger, LogLevel, ClientAuthError, AccountInfo
+    SilentFlowClient, ProtocolMode, Logger, LogLevel, ClientAuthError, AccountInfo, ServerAuthorizationCodeResponse
 } from '@azure/msal-common';
 import { CryptoProvider } from '../../src/crypto/CryptoProvider';
 import { DeviceCodeRequest } from '../../src/request/DeviceCodeRequest';
@@ -197,7 +197,7 @@ describe('PublicClientApplication', () => {
         );
     });
 
-    test('acquireTokenSilent', async () => {  
+    test('acquireTokenSilent', async () => {
         const account: AccountInfo = {
             homeAccountId: "",
             environment: "",
@@ -230,7 +230,7 @@ describe('PublicClientApplication', () => {
         const authApp = new PublicClientApplication(appConfig);
 
         let redirectUri: string;
-        
+
         const openBrowser = (url: string) => {
             expect(url.startsWith("https://login.microsoftonline.com")).toBe(true);
             http.get(`${redirectUri}?code=${TEST_CONSTANTS.AUTHORIZATION_CODE}`);
@@ -260,6 +260,62 @@ describe('PublicClientApplication', () => {
         expect(response.account).toEqual(mockAuthenticationResult.account);
     });
 
+    test("acquireTokenInteractive - with custom loopback client", async () => {
+        const authApp = new PublicClientApplication(appConfig);
+
+        const openBrowser = (url: string) => {
+            expect(url.startsWith("https://login.microsoftonline.com")).toBe(true);
+            return Promise.resolve();
+        };
+
+        const testServerCodeResponse: ServerAuthorizationCodeResponse = {
+            code: TEST_CONSTANTS.AUTHORIZATION_CODE,
+            client_info: TEST_DATA_CLIENT_INFO.TEST_DECODED_CLIENT_INFO,
+            state: "123"
+        };
+
+        const mockListenForAuthCode = jest.fn(() => {
+            return new Promise<ServerAuthorizationCodeResponse>((resolve) => {
+                resolve(testServerCodeResponse);
+            });
+        });
+        const mockGetRedirectUri = jest.fn(() => TEST_CONSTANTS.REDIRECT_URI);
+        const mockCloseServer = jest.fn(() => {});
+
+        const customLoopbackClient: ILoopbackClient = {
+            listenForAuthCode: mockListenForAuthCode,
+            getRedirectUri: mockGetRedirectUri,
+            closeServer: mockCloseServer
+        };
+
+        const request: InteractiveRequest = {
+            scopes: TEST_CONSTANTS.DEFAULT_GRAPH_SCOPE,
+            openBrowser: openBrowser,
+            loopbackClient: customLoopbackClient,
+        };
+
+        const MockAuthorizationCodeClient = getMsalCommonAutoMock().AuthorizationCodeClient;
+        jest.spyOn(msalCommon, 'AuthorizationCodeClient').mockImplementation((config) => new MockAuthorizationCodeClient(config));
+
+        jest.spyOn(MockAuthorizationCodeClient.prototype, "getAuthCodeUrl").mockImplementation((req) => {
+            expect(req.redirectUri).toEqual(TEST_CONSTANTS.REDIRECT_URI);
+            return Promise.resolve(TEST_CONSTANTS.AUTH_CODE_URL);
+        });
+
+        jest.spyOn(MockAuthorizationCodeClient.prototype, "acquireToken").mockImplementation((tokenRequest) => {
+            expect(tokenRequest.scopes).toEqual([...TEST_CONSTANTS.DEFAULT_GRAPH_SCOPE, ...TEST_CONSTANTS.DEFAULT_OIDC_SCOPES]);
+            return Promise.resolve(mockAuthenticationResult);
+        });
+
+        const response = await authApp.acquireTokenInteractive(request);
+        expect(response.idToken).toEqual(mockAuthenticationResult.idToken);
+        expect(response.accessToken).toEqual(mockAuthenticationResult.accessToken);
+        expect(response.account).toEqual(mockAuthenticationResult.account);
+        expect(mockListenForAuthCode).toHaveBeenCalledTimes(1);
+        expect(mockGetRedirectUri).toHaveBeenCalledTimes(1);
+        expect(mockCloseServer).toHaveBeenCalledTimes(1);
+    });
+
     test('initializeBaseRequest passes a claims hash to acquireToken', async () => {
         const account: AccountInfo = {
             homeAccountId: "",
@@ -345,7 +401,7 @@ describe('PublicClientApplication', () => {
         const authorityMock = setupAuthorityFactory_createDiscoveredInstance_mock(fakeAuthority);
 
         const authApp = new PublicClientApplication(config);
-        await authApp.acquireTokenByRefreshToken(request);        
+        await authApp.acquireTokenByRefreshToken(request);
         expect(authorityMock.mock.calls[0][0]).toBe(TEST_CONSTANTS.DEFAULT_AUTHORITY);
         expect(authorityMock.mock.calls[0][1]).toBeInstanceOf(HttpClient);
         expect(authorityMock.mock.calls[0][2]).toBeInstanceOf(NodeStorage);
@@ -490,7 +546,7 @@ describe('PublicClientApplication', () => {
 
        expect(authApp.getLogger()).toBeDefined();
        expect(authApp.getLogger().info("Test logger")).toEqual(undefined);
-        
+
     });
 
     test("should throw an error if state is not provided", async () => {
@@ -530,7 +586,7 @@ describe('PublicClientApplication', () => {
 
         try {
             await authApp.acquireTokenByCode(request, authCodePayLoad);
-        } catch (e) {   
+        } catch (e) {
             expect(mockInfo).toBeCalledWith("acquireTokenByCode called");
             expect(mockInfo).toHaveBeenCalledWith(
                 "acquireTokenByCode - validating state"
@@ -579,4 +635,4 @@ describe('PublicClientApplication', () => {
             .rejects.toMatchObject(ClientAuthError.createStateMismatchError());
     });
 
-});
+});

samples/msal-node-samples/ElectronSystemBrowserTestApp/package.json

@@ -9,6 +9,7 @@
         "start": "electron-forge start",
         "package": "electron-forge package",
         "build:package": "cd ../../../lib/msal-common && npm run build && cd ../msal-node && npm run build",
+        "install:local": "npm install ../../../lib/msal-common && npm install ../../../lib/msal-node",
         "make": "electron-forge make",
         "publish": "electron-forge publish",
         "lint": "eslint --ext .ts,.tsx ."
@@ -47,7 +48,8 @@
         "typescript": "~4.5.4"
     },
     "dependencies": {
-        "@azure/msal-node": "^1.14.2",
+        "@azure/msal-common": "file:../../../lib/msal-common",
+        "@azure/msal-node": "file:../../../lib/msal-node",
         "axios": "^1.1.3",
         "bootstrap": "^5.2.2",
         "electron-squirrel-startup": "^1.0.0"

samples/msal-node-samples/ElectronSystemBrowserTestApp/src/AuthProvider.ts

@@ -7,6 +7,7 @@ import {
     InteractiveRequest,
     SilentFlowRequest,
 } from "@azure/msal-node";
+import { CustomLoopbackClient } from "./CustomLoopbackClient";
 import { cachePlugin } from "./CachePlugin";
 import * as fs from "fs";
 
@@ -48,7 +49,7 @@ export default class AuthProvider {
         try {
             if (!this.account) {
                 return;
-            } 
+            }
             await this.clientApplication
                 .getTokenCache()
                 .removeAccount(this.account);
@@ -111,6 +112,13 @@ export default class AuthProvider {
         tokenRequest: SilentFlowRequest
     ): Promise<AuthenticationResult> {
         try {
+            /**
+             * A loopback server of your own implementation, which can have custom logic
+             * such as attempting to listen on a given port if it is available.
+             */
+            const customLoopbackClient = await CustomLoopbackClient.initialize(3874);
+
+            // opens a browser instance via Electron shell API
             const openBrowser = async (url: any) => {
                 await shell.openExternal(url);
             };
@@ -124,6 +132,7 @@ export default class AuthProvider {
                 errorTemplate: fs
                     .readFileSync("./public/errorTemplate.html", "utf8")
                     .toString(),
+                loopbackClient: customLoopbackClient // overrides default loopback client
             };
 
             const authResponse =