Merge pull request #1657 from AzureAD/sagonzal/msal-node-improve

[msal-node] Clean up public API

Author: sangonzal

lib/msal-common/src/index.ts

@@ -3,7 +3,9 @@ export { SPAClient } from "./client/SPAClient";
 export { AuthorizationCodeClient } from "./client/AuthorizationCodeClient";
 export { DeviceCodeClient } from "./client/DeviceCodeClient";
 export { RefreshTokenClient } from "./client/RefreshTokenClient";
-export { AuthOptions, SystemOptions, LoggerOptions, TelemetryOptions, DEFAULT_SYSTEM_OPTIONS } from "./config/ClientConfiguration";
+export {
+    AuthOptions, SystemOptions, LoggerOptions, TelemetryOptions, DEFAULT_SYSTEM_OPTIONS
+} from "./config/ClientConfiguration";
 export { ClientConfiguration } from "./config/ClientConfiguration";
 // Account
 export { Account } from "./account/Account";
@@ -42,5 +44,7 @@ export { ServerError } from "./error/ServerError";
 export { ClientAuthError, ClientAuthErrorMessage } from "./error/ClientAuthError";
 export { ClientConfigurationError, ClientConfigurationErrorMessage } from "./error/ClientConfigurationError";
 // Constants and Utils
-export { Constants, PromptValue, TemporaryCacheKeys, PersistentCacheKeys } from "./utils/Constants";
+export {
+    Constants, PromptValue, TemporaryCacheKeys, PersistentCacheKeys, Prompt, ResponseMode
+} from "./utils/Constants";
 export { StringUtils } from "./utils/StringUtils";

lib/msal-common/src/request/AuthorizationCodeUrlRequest.ts

@@ -3,8 +3,11 @@
  * Licensed under the MIT License.
  */
 
+import { Prompt, ResponseMode } from "../utils/Constants";
+
 /**
- * @type AuthorizationCodeUrlRequest: Request object passed by user to retrieve a Code from the server (first leg of authorization code grant flow)
+ * @type AuthorizationCodeUrlRequest: Request object passed by user to retrieve a Code from the
+ * server (first leg of authorization code grant flow)
  */
 export type AuthorizationCodeUrlRequest = {
 
@@ -20,15 +23,17 @@ export type AuthorizationCodeUrlRequest = {
     scopes: Array<string>;
 
     /**
-     * Url of the authority which the application acquires tokens from
+     * Url of the authority which the application acquires tokens from. Defaults to
+     * https://login.microsoftonline.com/common. If using the same authority for all request, authority should set
+     * on client application object and not request, to avoid resolving authority endpoints multiple times.
      */
     authority?: string;
 
     /**
      * Specifies the method that should be used to send the authentication result to your app.
      * Can be query, form_post, or fragment. If no value is passed in, it defaults to query.
      */
-    responseMode?: string;
+    responseMode?: ResponseMode;
 
     /**
      * Used to secure authorization code grant via Proof of Key for Code Exchange (PKCE).
@@ -37,8 +42,8 @@ export type AuthorizationCodeUrlRequest = {
     codeChallenge?: string;
 
     /**
-     * The method used to encode the code verifier for the code challenge parameter. Can be one
-     * of plain or S256. If excluded, code challenge is assumed to be plaintext. For more
+     * The method used to encode the code verifier for the code challenge parameter. Can be
+     * "plain" or "S256". If excluded, code challenge is assumed to be plaintext. For more
      * information, see the PKCE RCF: https://tools.ietf.org/html/rfc7636
      */
     codeChallengeMethod?: string;
@@ -53,8 +58,17 @@ export type AuthorizationCodeUrlRequest = {
 
     /**
      * Indicates the type of user interaction that is required.
+     *
+     * login: will force the user to enter their credentials on that request, negating single-sign on
+     *
+     * none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via
+     *        single-sign on, the endpoint will return an interaction_required error
+     * consent: will the trigger the OAuth consent dialog after the user signs in, asking the user to grant permissions
+     *          to the app
+     * select_account: will interrupt single sign-=on providing account selection experience listing all the accounts in
+     *                 session or any remembered accounts or an option to choose to use a different account
      */
-    prompt?: string;
+    prompt?: Prompt;
 
     /**
      * Can be used to pre-fill the username/email address field of the sign-in page for the user,
@@ -77,8 +91,8 @@ export type AuthorizationCodeUrlRequest = {
     claims?: string;
 
     /**
-     *  A value included in the request that is also returned in the token response. A randomly
-     *  generated unique value is typically used for preventing cross site request forgery attacks.
+     *  A value included in the request that is returned in the id token. A randomly
+     *  generated unique value is typically used to mitigate replay attacks.
      */
     nonce?: string;
 

lib/msal-common/src/request/DeviceCodeRequest.ts

@@ -30,8 +30,9 @@ export type DeviceCodeRequest = {
     cancel?: boolean;
 
     /**
-     * URI of the authority from which MSAL will acquire the tokens from. If this value is not set, MSAL defaults
-     * to the authority used when configuring the PublicClientApplication.
+     * Url of the authority which the application acquires tokens from. Defaults to
+     * https://login.microsoftonline.com/common. If using the same authority for all request, authority should set
+     * on client application object and not request, to avoid resolving authority endpoints multiple times.
      */
     authority?: string;
 };

lib/msal-common/src/server/RequestParameterBuilder.ts

@@ -3,8 +3,7 @@
 * Licensed under the MIT License.
 */
 
-import { AADServerParamKeys, SSOTypes } from "../utils/Constants";
-import { Constants } from "../utils/Constants";
+import { AADServerParamKeys, Constants, Prompt, ResponseMode, SSOTypes } from "../utils/Constants";
 import { ScopeSet } from "../request/ScopeSet";
 import { ClientConfigurationError } from "../error/ClientConfigurationError";
 
@@ -29,10 +28,10 @@ export class RequestParameterBuilder {
      * add response_mode. defaults to query.
      * @param responseMode
      */
-    addResponseMode(responseMode?: string): void {
+    addResponseMode(responseMode?: ResponseMode): void {
         this.parameters.set(
             AADServerParamKeys.RESPONSE_MODE,
-            encodeURIComponent((responseMode) ? responseMode : Constants.QUERY_RESPONSE_MODE)
+            encodeURIComponent((responseMode) ? responseMode : ResponseMode.QUERY)
         );
     }
 
@@ -100,7 +99,7 @@ export class RequestParameterBuilder {
      * add prompt
      * @param prompt
      */
-    addPrompt(prompt: string): void {
+    addPrompt(prompt: Prompt): void {
         this.parameters.set(`${AADServerParamKeys.PROMPT}`, encodeURIComponent(prompt));
     }
 

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

@@ -34,7 +34,6 @@ export const Constants = {
     CODE_GRANT_TYPE: "authorization_code",
     RT_GRANT_TYPE: "refresh_token",
     FRAGMENT_RESPONSE_MODE: "fragment",
-    QUERY_RESPONSE_MODE: "query",
     S256_CODE_CHALLENGE_METHOD: "S256",
     URL_FORM_CONTENT_TYPE: "application/x-www-form-urlencoded;charset=utf-8",
     AUTHORIZATION_PENDING: "authorization_pending"
@@ -45,7 +44,7 @@ export const Constants = {
  */
 export enum HeaderNames {
     CONTENT_TYPE = "Content-Type"
-};
+}
 
 /**
  * Temporary cache keys for MSAL, deleted after any request.
@@ -61,7 +60,7 @@ export enum TemporaryCacheKeys {
     URL_HASH = "urlHash",
     REQUEST_PARAMS = "request.params",
     SCOPES = "scopes"
-};
+}
 
 /**
  * Persistent cache keys MSAL which stay while user is logged in.
@@ -72,7 +71,7 @@ export enum PersistentCacheKeys {
     ADAL_ID_TOKEN = "adal.idtoken",
     ERROR = "error",
     ERROR_DESC = "error.description"
-};
+}
 
 /**
  * List of pre-established trusted host URLs.
@@ -93,7 +92,7 @@ export enum AADAuthorityConstants {
     COMMON = "common",
     ORGANIZATIONS = "organizations",
     CONSUMERS = "consumers"
-};
+}
 
 /**
  * Keys in the hashParams sent by AAD Server
@@ -129,7 +128,7 @@ export enum AADServerParamKeys {
     X_CLIENT_CPU = "x-client-CPU",
     POST_LOGOUT_URI = "post_logout_redirect_uri",
     DEVICE_CODE = "device_code"
-};
+}
 
 /**
  * IdToken claim string constants
@@ -168,13 +167,13 @@ export enum SSOTypes {
     ACCOUNT = "account",
     SID = "sid",
     LOGIN_HINT = "login_hint",
-    ID_TOKEN ="id_token",
+    ID_TOKEN = "id_token",
     DOMAIN_HINT = "domain_hint",
     ORGANIZATIONS = "organizations",
     CONSUMERS = "consumers",
     ACCOUNT_ID = "accountIdentifier",
     HOMEACCOUNT_ID = "homeAccountIdentifier"
-};
+}
 
 /**
  * Disallowed extra query parameters.
@@ -193,7 +192,9 @@ export const CodeChallengeMethodValues = {
 };
 
 /**
- *
+ * The method used to encode the code verifier for the code challenge parameter. can be one
+ * of plain or s256. if excluded, code challenge is assumed to be plaintext. for more
+ * information, see the pkce rcf: https://tools.ietf.org/html/rfc7636
  */
 export const CodeChallengeMethodValuesArray: string[] = [
     CodeChallengeMethodValues.PLAIN,
@@ -209,6 +210,16 @@ export enum ResponseMode {
     FORM_POST = "form_post"
 }
 
+/**
+ * Allowed values for prompt
+ */
+export enum Prompt {
+    LOGIN = "login",
+    NONE = "none",
+    CONSENT = "consent",
+    SELECT_ACCOUNT = "select_account"
+}
+
 /**
  * allowed grant_type
  */
@@ -219,5 +230,5 @@ export enum GrantType {
     RESOURCE_OWNER_PASSWORD_GRANT = "password",
     REFRESH_TOKEN_GRANT = "refresh_token",
     DEVICE_CODE_GRANT = "device_code"
-};
+}
 

lib/msal-common/test/client/AuthorizationCodeClient.spec.ts

@@ -58,7 +58,7 @@ describe("AuthorizationCodeClient unit tests", () => {
             expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_TYPE}=${Constants.CODE_RESPONSE_TYPE}`);
             expect(loginUrl).to.contain(`${AADServerParamKeys.CLIENT_ID}=${TEST_CONFIG.MSAL_CLIENT_ID}`);
             expect(loginUrl).to.contain(`${AADServerParamKeys.REDIRECT_URI}=${encodeURIComponent(TEST_URIS.TEST_REDIRECT_URI_LOCALHOST)}`);
-            expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_MODE}=${encodeURIComponent(Constants.QUERY_RESPONSE_MODE)}`);
+            expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_MODE}=${encodeURIComponent(ResponseMode.QUERY)}`);
         });
 
         it("Creates an authorization url passing in a default scope", async () => {
@@ -78,7 +78,7 @@ describe("AuthorizationCodeClient unit tests", () => {
             expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_TYPE}=${Constants.CODE_RESPONSE_TYPE}`);
             expect(loginUrl).to.contain(`${AADServerParamKeys.CLIENT_ID}=${TEST_CONFIG.MSAL_CLIENT_ID}`);
             expect(loginUrl).to.contain(`${AADServerParamKeys.REDIRECT_URI}=${encodeURIComponent(TEST_URIS.TEST_REDIRECT_URI_LOCALHOST)}`);
-            expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_MODE}=${encodeURIComponent(Constants.QUERY_RESPONSE_MODE)}`)
+            expect(loginUrl).to.contain(`${AADServerParamKeys.RESPONSE_MODE}=${encodeURIComponent(ResponseMode.QUERY)}`);
         });
 
         it("Creates an authorization url passing in optional parameters", async () => {

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

@@ -24,32 +24,20 @@ import { Constants as NodeConstants } from "./../utils/Constants";
 
 export abstract class ClientApplication {
 
-    protected config: Configuration;
-    protected _authority: Authority;
+    private config: Configuration;
+    private _authority: Authority;
+    private readonly cryptoProvider: CryptoProvider;
+    private readonly storage: Storage;
 
     /**
      * @constructor
-     * Constructor for the ClientApplication to instantiate the PublicClientApplication object
-     *
-     * Important attributes in the Configuration object for auth are:
-     * - clientID: the application ID of your application. You can obtain one by registering your application with our Application registration portal
-     * - authority: the authority URL for your application.
-     * - redirect_uri: the uri of your application registered in the portal.
-     *
-     * In Azure AD, authority is a URL indicating the Azure active directory that MSAL uses to obtain tokens.
-     * It is of the form https://login.microsoftonline.com/{Enter_the_Tenant_Info_Here}
-     * If your application supports Accounts in one organizational directory, replace "Enter_the_Tenant_Info_Here" value with the Tenant Id or Tenant name (for example, contoso.microsoft.com).
-     * If your application supports Accounts in any organizational directory, replace "Enter_the_Tenant_Info_Here" value with organizations.
-     * If your application supports Accounts in any organizational directory and personal Microsoft accounts, replace "Enter_the_Tenant_Info_Here" value with common.
-     * To restrict support to Personal Microsoft accounts only, replace "Enter_the_Tenant_Info_Here" value with consumers.
-     *
-     * In Azure B2C, authority is of the form https://{instance}/tfp/{tenant}/{policyName}/ls
-     *
-     * @param {@link (Configuration:type)} configuration object for the MSAL PublicClientApplication instance
-     */
+     * Constructor for the ClientApplication
+    */
     protected constructor(configuration: Configuration) {
         this.config = buildAppConfiguration(configuration);
 
+        this.cryptoProvider = new CryptoProvider();
+        this.storage = new Storage(this.config.auth.clientId, this.config.cache!);
         B2cAuthority.setKnownAuthorities(this.config.auth.knownAuthorities!);
     }
 
@@ -114,9 +102,9 @@ export abstract class ClientApplication {
                 loggerCallback: this.config.system!.loggerOptions!.loggerCallback,
                 piiLoggingEnabled: this.config.system!.loggerOptions!.piiLoggingEnabled,
             },
-            cryptoInterface: new CryptoProvider(),
+            cryptoInterface: this.cryptoProvider,
             networkInterface: this.config.system!.networkClient,
-            storageInterface: new Storage(this.config.auth!.clientId, this.config.cache!),
+            storageInterface: this.storage,
             libraryInfo: {
                 sku: NodeConstants.MSAL_SKU,
                 version: version,

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

@@ -12,22 +12,25 @@ import { ClientApplication } from './ClientApplication';
  * are not trusted to safely store application secrets, and therefore can only request tokens in the name of an user.
  */
 export class PublicClientApplication extends ClientApplication {
+
     /**
      * @constructor
-     * Constructor for the PublicClientApplication
      *
-     * Required attributes in the Configuration object are:
-     * - clientID: the application ID of your application. You can obtain one by registering your application with our Application registration portal
+     * Important attributes in the Configuration object for auth are:
+     * - clientID: the application ID of your application. ou can obtain one by registering your application with our Application registration portal
      * - authority: the authority URL for your application.
      *
-     * In Azure AD, authority is a URL indicating of the form https://login.microsoftonline.com/{Enter_the_Tenant_Info_Here}.
+     * AAD authorities are of the form https://login.microsoftonline.com/{Enter_the_Tenant_Info_Here}
      * If your application supports Accounts in one organizational directory, replace "Enter_the_Tenant_Info_Here" value with the Tenant Id or Tenant name (for example, contoso.microsoft.com).
      * If your application supports Accounts in any organizational directory, replace "Enter_the_Tenant_Info_Here" value with organizations.
      * If your application supports Accounts in any organizational directory and personal Microsoft accounts, replace "Enter_the_Tenant_Info_Here" value with common.
      * To restrict support to Personal Microsoft accounts only, replace "Enter_the_Tenant_Info_Here" value with consumers.
      *
-     * In Azure B2C, authority is of the form https://{instance}/tfp/{tenant}/{policyName}/
-     * Full B2C functionality will be available in this library in future versions.
+     * Azure B2C authorities are of the form https://{instance}/{tenant}/{policy}. Each policy is considered
+     * it's own authority. You will have to set the all of the knownAuthorities at the time of the client application
+     * construction
+     *
+     * ADFS authorities are of the form https://{instance}/adfs
      *
      * @param {@link (Configuration:type)} configuration object for the MSAL PublicClientApplication instance
      */

lib/msal-node/src/config/Configuration.ts

@@ -11,6 +11,11 @@ import { NetworkUtils } from '../utils/NetworkUtils';
 import { CACHE } from '../utils/Constants';
 import debug from "debug";
 
+/**
+ * - clientId               - Client id of the application.
+ * - authority              - Url of the authority. If no value is set, defaults to https://login.microsoftonline.com/common.
+ * - knownAuthorities       - Needed for Azure B2C. All authorities that will be used in the client application.
+ */
 export type NodeAuthOptions = {
     clientId: string;
     authority?: string;
@@ -33,7 +38,7 @@ export type CacheOptions = {
  * Type for configuring logger and http client options
  *
  * - logger                       - Used to initialize the Logger object; TODO: Expand on logger details or link to the documentation on logger
- * - networkClient                -
+ * - networkClient                - Http client used for all http get and post calls. Defaults to using MSAL's default http client.
  */
 export type NodeSystemOptions = {
     loggerOptions?: LoggerOptions;
@@ -43,10 +48,9 @@ export type NodeSystemOptions = {
 /**
  * Use the configuration object to configure MSAL and initialize the client application object
  *
- * This object allows you to configure important elements of MSAL functionality:
  * - auth: this is where you configure auth elements like clientID, authority used for authenticating against the Microsoft Identity Platform
- * - cache: this is where you configure cache location and whether to store cache in cookies
- * - system: this is where you can configure the network client, logger, token renewal offset, and telemetry
+ * - cache: this is where you configure cache location
+ * - system: this is where you can configure the network client, logger
  */
 export type Configuration = {
     auth: NodeAuthOptions;

lib/msal-node/src/index.ts

@@ -11,7 +11,9 @@ export {
     // Request
     AuthorizationCodeRequest,
     DeviceCodeRequest,
-    TokenExchangeParameters,
+    RefreshTokenRequest,
+    Prompt,
+    ResponseMode,
     // Response
     AuthResponse,
     // Error