Merge pull request #4106 from AzureAD/cloudinstance-authority-enum

Add AzureCloudInstance to JS libraries

Author: sameerag

change/@azure-msal-browser-a7a11b2b-3e4b-4a25-8480-77443ff2d9ea.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add AzureCloudInstance to JS libraries",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-6a04f8da-2ee0-401e-bced-3f276384a03c.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "Add AzureCloudInstance to JS libraries",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-6bc56920-ff6f-4734-9122-20465077fc6d.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add AzureCloudInstance to JS libraries",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

lib/msal-browser/FAQ.md

@@ -239,6 +239,10 @@ For MSAL.js 2.x, please review [this document](https://github.com/AzureAD/micros
 
 The `authority` string that you need to supplant to MSAL app configuration is not explicitly listed among the **Endpoint** links on `Azure Portal/AzureAD/App Registration/Overview` page. It is simply the domain part of a `/token` or `/authorize` endpoint, followed by the tenant name or ID e.g. `https://login.microsoftonline.com/common`.
 
+## What does authority string default to if I provide "authority" and "azureCloudOptions"?
+
+If the developer provides `azureCloudOptions`, MSAL.js will overwrite any value provided in the `authority`. MSAL.js will also give preference to the parameters provided in a `request` over `configuration`. Please note that if `azureCloudOptions` are set in the configuration, they will take precedence over `authority` in the `request`. If the developer needs to overwrite this, they need to set `azureCloudOptions` in the `request`.
+
 ## What should I set my `redirectUri` to?
 
 When you attempt to authenticate MSAL will navigate to your IDP's sign in page either in the current window, a popup window or a hidden iframe depending on whether you used a redirect, popup or silent API respectively. When authentication is complete the IDP will redirect the window to the `redirectUri` specified in the request with the authentication response in the url hash. You can use any page in your application as your `redirectUri` but there are some additional considerations you should be aware of depending on which API you are using. All pages used as a `redirectUri` **must** be registered as a Reply Url of type "SPA" on your app registration.
@@ -262,7 +266,7 @@ The library is built to specifically use the fragment response mode. This is a s
 
 ## How do I configure the position and dimensions of popups?
 
-A popup window's position and dimension can be configured by passing the height, width, top position, and left position in the request. If no configurations are passed, MSAL defaults will be used. See the request documentation for [PopupRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_browser.html#popuprequest) and [EndSessionPopupRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_browser.html#endsessionpopuprequest) for more details. 
+A popup window's position and dimension can be configured by passing the height, width, top position, and left position in the request. If no configurations are passed, MSAL defaults will be used. See the request documentation for [PopupRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_browser.html#popuprequest) and [EndSessionPopupRequest](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_browser.html#endsessionpopuprequest) for more details.
 
 Note that popup dimensions should be positioned on screen and sized smaller than the parent window. Popups that are positioned off-screen or larger than the parent window will use MSAL defaults instead.
 
@@ -312,7 +316,7 @@ Please refer to our performance guide [here](https://github.com/AzureAD/microsof
 
 ## I'm seeing scopes `openid`, `profile`, `email`, `offline_access` and `User.Read` in my tokens, even though I haven't requested them. What are they?
 
-The first four (`openid`, `profile`, `email` and `offline_access`) are called **default scopes**. They are added to Azure AD as part of Azure AD - OAuth 2.0/OpenID Connect compliance. They are **not** part of any particular API. You can read more about them [here](https://openid.net/specs/openid-connect-core-1_0.html). 
+The first four (`openid`, `profile`, `email` and `offline_access`) are called **default scopes**. They are added to Azure AD as part of Azure AD - OAuth 2.0/OpenID Connect compliance. They are **not** part of any particular API. You can read more about them [here](https://openid.net/specs/openid-connect-core-1_0.html).
 
 The scope `User.Read`, on the other hand, is an MS Graph API scope. It is also added by default to every app registration. However if your application is not calling MS Graph API, you can simply ignore it.
 
@@ -366,7 +370,7 @@ Our recommendation is to move to the new password reset experience since it simp
 pca.loginPopup()
     .then((response) => {
         // do something with auth response
-    }).catch(error => {     
+    }).catch(error => {
         // Error handling
         if (error.errorMessage) {
             // Check for forgot password error

lib/msal-browser/docs/configuration.md

@@ -73,6 +73,7 @@ const msalInstance = new PublicClientApplication(msalConfig);
 | `navigateToLoginRequestUrl` | If `true`, will navigate back to the original request location before processing the authorization code response. If the `redirectUri` is the same as the original request location, this flag should be set to false. | boolean | `true` |
 | `clientCapabilities` | Array of capabilities to be added to all network requests as part of the `xms_cc` claims request | Array of strings | [] |
 | `protocolMode` | Enum representing the protocol mode to use. If `"AAD"`, will function on the OIDC-compliant AAD v2 endpoints; if `"OIDC"`, will function on other OIDC-compliant endpoints. | string | `"AAD"` |
+| `azureCloudOptions` | A defined set of azure cloud options for developers to default to their specific cloud authorities, for specific clouds supported please refer to the [AzureCloudInstance](aka.ms/msaljs/azure_cloud_instance) | [AzureCloudOptions](https://azuread.github.io/microsoft-authentication-library-for-js/ref/modules/_azure_msal_common.html#azurecloudoptions) | [AzureCloudInstance.None](msaljs/azure_cloud_instance)
 
 ### Cache Config Options
 

lib/msal-browser/src/cache/TokenCache.ts

@@ -37,12 +37,12 @@ export class TokenCache implements ITokenCache {
         this.logger = logger;
         this.cryptoObj = cryptoObj;
     }
-    
+
     // Move getAllAccounts here and cache utility APIs
 
     /**
-     * API to load tokens to msal-browser cache. 
-     * @param request 
+     * API to load tokens to msal-browser cache.
+     * @param request
      * @param response
      * @param options
      */
@@ -58,13 +58,14 @@ export class TokenCache implements ITokenCache {
             this.loadAccessToken(request, response, request.account.homeAccountId, request.account.environment, request.account.tenantId, options);
         } else if (request.authority) {
 
+            const authorityUrl = Authority.generateAuthority(request.authority, request.azureCloudOptions);
             const authorityOptions: AuthorityOptions = {
                 protocolMode: this.config.auth.protocolMode,
                 knownAuthorities: this.config.auth.knownAuthorities,
                 cloudDiscoveryMetadata: this.config.auth.cloudDiscoveryMetadata,
-                authorityMetadata: this.config.auth.authorityMetadata
+                authorityMetadata: this.config.auth.authorityMetadata,
             };
-            const authority = new Authority(request.authority, this.config.system.networkClient, this.storage, authorityOptions);
+            const authority = new Authority(authorityUrl, this.config.system.networkClient, this.storage, authorityOptions);
 
             // "clientInfo" from options takes precedence over "clientInfo" in response
             if (options.clientInfo) {
@@ -85,11 +86,11 @@ export class TokenCache implements ITokenCache {
 
     /**
      * Helper function to load id tokens to msal-browser cache
-     * @param idToken 
-     * @param homeAccountId 
-     * @param environment 
-     * @param tenantId 
-     * @param options 
+     * @param idToken
+     * @param homeAccountId
+     * @param environment
+     * @param tenantId
+     * @param options
      */
     private loadIdToken(idToken: string, homeAccountId: string, environment: string, tenantId: string, options: LoadTokenOptions): void {
 
@@ -110,13 +111,13 @@ export class TokenCache implements ITokenCache {
 
     /**
      * Helper function to load access tokens to msal-browser cache
-     * @param request 
-     * @param response 
-     * @param options 
-     * @param homeAccountId 
-     * @param environment 
-     * @param tenantId 
-     * @returns 
+     * @param request
+     * @param response
+     * @param options
+     * @param homeAccountId
+     * @param environment
+     * @param tenantId
+     * @returns
      */
     private loadAccessToken(request: SilentRequest, response: ExternalTokenResponse, homeAccountId: string, environment: string, tenantId: string, options: LoadTokenOptions): void {
 
@@ -132,7 +133,7 @@ export class TokenCache implements ITokenCache {
         if (!options.extendedExpiresOn) {
             throw BrowserAuthError.createUnableToLoadTokenError("Please provide an extendedExpiresOn value in the options.");
         }
-        
+
         const scopes = new ScopeSet(request.scopes).printScopes();
         const expiresOn = response.expires_in;
         const extendedExpiresOn = options.extendedExpiresOn;

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

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { SystemOptions, LoggerOptions, INetworkModule, DEFAULT_SYSTEM_OPTIONS, Constants, ProtocolMode, LogLevel, StubbedNetworkModule } from "@azure/msal-common";
+import { SystemOptions, LoggerOptions, INetworkModule, DEFAULT_SYSTEM_OPTIONS, Constants, ProtocolMode, LogLevel, StubbedNetworkModule, AzureCloudInstance, AzureCloudOptions } from "@azure/msal-common";
 import { BrowserUtils } from "../utils/BrowserUtils";
 import { BrowserCacheLocation } from "../utils/BrowserConstants";
 import { INavigationClient } from "../navigation/INavigationClient";
@@ -21,11 +21,11 @@ export const DEFAULT_REDIRECT_TIMEOUT_MS = 30000;
  * - authority                   - You can configure a specific authority, defaults to " " or "https://login.microsoftonline.com/common"
  * - knownAuthorities            - An array of URIs that are known to be valid. Used in B2C scenarios.
  * - cloudDiscoveryMetadata      - A string containing the cloud discovery response. Used in AAD scenarios.
- * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
- * - postLogoutRedirectUri      - The redirect URI where the window navigates after a successful logout.
- * - navigateToLoginRequestUrl  - Boolean indicating whether to navigate to the original request URL after the auth server navigates to the redirect URL.
- * - clientCapabilities         - Array of capabilities which will be added to the claims.access_token.xms_cc request property on every network request.
- * - protocolMode               - Enum that represents the protocol that msal follows. Used for configuring proper endpoints.
+ * - redirectUri                 - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
+ * - postLogoutRedirectUri       - The redirect URI where the window navigates after a successful logout.
+ * - navigateToLoginRequestUrl   - Boolean indicating whether to navigate to the original request URL after the auth server navigates to the redirect URL.
+ * - clientCapabilities          - Array of capabilities which will be added to the claims.access_token.xms_cc request property on every network request.
+ * - protocolMode                - Enum that represents the protocol that msal follows. Used for configuring proper endpoints.
  */
 export type BrowserAuthOptions = {
     clientId: string;
@@ -38,14 +38,15 @@ export type BrowserAuthOptions = {
     navigateToLoginRequestUrl?: boolean;
     clientCapabilities?: Array<string>;
     protocolMode?: ProtocolMode;
+    azureCloudOptions?: AzureCloudOptions;
 };
 
 /**
  * Use this to configure the below cache configuration options:
  *
- * - cacheLocation            - Used to specify the cacheLocation user wants to set. Valid values are "localStorage" and "sessionStorage"
- * - storeAuthStateInCookie   - If set, MSAL stores the auth request state required for validation of the auth flows in the browser cookies. By default this flag is set to false.
- * - secureCookies            - If set, MSAL sets the "Secure" flag on cookies so they can only be sent over HTTPS. By default this flag is set to false.
+ * - cacheLocation              - Used to specify the cacheLocation user wants to set. Valid values are "localStorage" and "sessionStorage"
+ * - storeAuthStateInCookie     - If set, MSAL stores the auth request state required for validation of the auth flows in the browser cookies. By default this flag is set to false.
+ * - secureCookies              - If set, MSAL sets the "Secure" flag on cookies so they can only be sent over HTTPS. By default this flag is set to false.
  */
 export type CacheOptions = {
     cacheLocation?: BrowserCacheLocation | string;
@@ -122,7 +123,11 @@ export function buildConfiguration({ auth: userInputAuth, cache: userInputCache,
         postLogoutRedirectUri: "",
         navigateToLoginRequestUrl: true,
         clientCapabilities: [],
-        protocolMode: ProtocolMode.AAD
+        protocolMode: ProtocolMode.AAD,
+        azureCloudOptions: {
+            azureCloudInstance: AzureCloudInstance.None,
+            tenant: ""
+        },
     };
 
     // Default cache options for browser

lib/msal-browser/src/index.ts

@@ -12,11 +12,11 @@ export { PublicClientApplication } from "./app/PublicClientApplication";
 export { Configuration, BrowserAuthOptions, CacheOptions, BrowserSystemOptions, BrowserConfiguration, DEFAULT_IFRAME_TIMEOUT_MS } from "./config/Configuration";
 export { InteractionType, InteractionStatus, BrowserCacheLocation, WrapperSKU, ApiId } from "./utils/BrowserConstants";
 export { BrowserUtils } from "./utils/BrowserUtils";
- 
+
 // Browser Errors
 export { BrowserAuthError, BrowserAuthErrorMessage } from "./error/BrowserAuthError";
 export { BrowserConfigurationAuthError, BrowserConfigurationAuthErrorMessage } from "./error/BrowserConfigurationAuthError";
- 
+
 // Interfaces
 export { IPublicClientApplication, stubbedPublicClientApplication } from "./app/IPublicClientApplication";
 export { INavigationClient } from "./navigation/INavigationClient";
@@ -30,34 +30,34 @@ export { EndSessionRequest } from "./request/EndSessionRequest";
 export { EndSessionPopupRequest } from "./request/EndSessionPopupRequest";
 export { AuthorizationUrlRequest } from "./request/AuthorizationUrlRequest";
 export { AuthorizationCodeRequest } from "./request/AuthorizationCodeRequest";
- 
+
 // Cache
 export { LoadTokenOptions } from "./cache/TokenCache";
 export { BrowserCacheManager } from "./cache/BrowserCacheManager";
- 
+
 // Clients
 export { StandardInteractionClient } from "./interaction_client/StandardInteractionClient";
 export { RedirectClient } from "./interaction_client/RedirectClient";
 export { PopupClient } from "./interaction_client/PopupClient";
 export { SilentIframeClient } from "./interaction_client/SilentIframeClient";
 export { SilentCacheClient } from "./interaction_client/SilentCacheClient";
 export { SilentRefreshClient } from "./interaction_client/SilentRefreshClient";
- 
+
 // Handlers
 export { RedirectHandler } from "./interaction_handler/RedirectHandler";
- 
+
 // Events
 export { EventMessage, EventPayload, EventError, EventCallbackFunction, EventMessageUtils, PopupEvent } from "./event/EventMessage";
 export { EventType } from "./event/EventType";
 export { EventHandler } from "./event/EventHandler";
- 
+
 export { SignedHttpRequest, SignedHttpRequestOptions } from "./crypto/SignedHttpRequest";
- 
+
 // Utilities
 export { BrowserStateObject } from "./utils/BrowserProtocolUtils";
 export { BrowserConstants, TemporaryCacheKeys } from "./utils/BrowserConstants";
 export { PopupUtils } from "./utils/PopupUtils";
- 
+
 // Common Object Formats
 export {
     AuthenticationScheme,
@@ -91,8 +91,11 @@ export {
     // Utils
     StringUtils,
     UrlString,
+    // AzureCloudInstance enum
+    AzureCloudInstance,
+    AzureCloudOptions,
     AuthenticationHeaderParser,
     OIDC_DEFAULT_SCOPES
 } from "@azure/msal-common";
- 
+
 export { version } from "./packageMetadata";

lib/msal-browser/src/interaction_client/PopupClient.ts

@@ -17,7 +17,7 @@ import { PopupRequest } from "../request/PopupRequest";
 export class PopupClient extends StandardInteractionClient {
     /**
      * Acquires tokens by opening a popup window to the /authorize endpoint of the authority
-     * @param request 
+     * @param request
      */
     acquireToken(request: PopupRequest): Promise<AuthenticationResult> {
         try {
@@ -42,7 +42,7 @@ export class PopupClient extends StandardInteractionClient {
 
     /**
      * Clears local cache for the current user then opens a popup window prompting the user to sign-out of the server
-     * @param logoutRequest 
+     * @param logoutRequest
      */
     logout(logoutRequest?: EndSessionPopupRequest): Promise<void> {
         try {
@@ -91,7 +91,7 @@ export class PopupClient extends StandardInteractionClient {
             const authCodeRequest: CommonAuthorizationCodeRequest = await this.initializeAuthorizationCodeRequest(validRequest);
 
             // Initialize the client
-            const authClient: AuthorizationCodeClient = await this.createAuthCodeClient(serverTelemetryManager, validRequest.authority);
+            const authClient: AuthorizationCodeClient = await this.createAuthCodeClient(serverTelemetryManager, validRequest.authority, validRequest.azureCloudOptions);
             this.logger.verbose("Auth code client created");
 
             // Create acquire token url.
@@ -120,7 +120,7 @@ export class PopupClient extends StandardInteractionClient {
             const result = await interactionHandler.handleCodeResponseFromHash(hash, state, authClient.authority, this.networkClient);
 
             return result;
-        } catch (e) {            
+        } catch (e) {
             if (popup) {
                 // Close the synchronous popup if an error is thrown before the window unload event is registered
                 popup.close();
@@ -137,20 +137,20 @@ export class PopupClient extends StandardInteractionClient {
     }
 
     /**
-     * 
-     * @param validRequest 
-     * @param popupName 
+     *
+     * @param validRequest
+     * @param popupName
      * @param requestAuthority
-     * @param popup 
-     * @param mainWindowRedirectUri 
-     * @param popupWindowAttributes 
+     * @param popup
+     * @param mainWindowRedirectUri
+     * @param popupWindowAttributes
      */
     protected async logoutPopupAsync(validRequest: CommonEndSessionRequest, popupName: string, popupWindowAttributes: PopupWindowAttributes, requestAuthority?: string, popup?: Window|null, mainWindowRedirectUri?: string): Promise<void> {
         this.logger.verbose("logoutPopupAsync called");
         this.eventHandler.emitEvent(EventType.LOGOUT_START, InteractionType.Popup, validRequest);
 
         const serverTelemetryManager = this.initializeServerTelemetryManager(ApiId.logoutPopup);
-        
+
         try {
             // Clear cache on logout
             await this.clearCacheOnLogout(validRequest.account);
@@ -202,7 +202,7 @@ export class PopupClient extends StandardInteractionClient {
             if (e instanceof AuthError) {
                 e.setCorrelationId(this.correlationId);
             }
-            
+
             this.browserStorage.setInteractionInProgress(false);
             this.eventHandler.emitEvent(EventType.LOGOUT_FAILURE, InteractionType.Popup, null, e);
             this.eventHandler.emitEvent(EventType.LOGOUT_END, InteractionType.Popup);