Test cross-repo references for msal.js

.openpublishing.publish.config.json

@@ -41,20 +41,12 @@
   "sync_notification_subscribers": [],
   "branches_to_filter": [],
   "need_preview_pull_request": true,
-  "dependent_repositories": [
-    {
-      "path_to_root": "_themes",
-      "url": "https://github.com/Microsoft/templates.docs.msft",
-      "branch": "main",
-      "branch_mapping": {}
-    }
-  ],
   "branch_target_mapping": {},
   "docs_build_engine": {},
   "skip_source_output_uploading": false,
   "JoinTOCPlugin": [
     {
-      "TopLevelTOC": "msal/docs-ref-toc/fxtoc.yml",
+      "TopLevelTOC": "msal/docs-ref-toc/.yml",
       "ReferenceTOC": "msal/docs-ref-autogen/toc.yml",
       "ReferenceTOCUrl": "/javascript/api/microsoft-authentication-library-js/toc.json?view=msal-js-latest",
       "ConceptualTOCUrl": "/microsoft-authentication-library-js/toc.json",
@@ -67,6 +59,21 @@
       }
     }
   ],
+  "dependent_repositories": [
+    {
+      "path_to_root": "_themes",
+      "url": "https://github.com/Microsoft/templates.docs.msft",
+      "branch": "main",
+      "branch_mapping": {}
+    },
+    {
+      "path_to_root": "lib",
+      "url": "https://github.com/AzureAD/microsoft-authentication-library-for-js",
+      "branch": "test-cross-repo-reference",
+      "branch_mapping": {}
+    }
+  ],
+  "branch_target_mapping": {},
   "dependent_packages": [
     {
       "id": "opbuild.templates.uref",

msal-javascript-conceptual/docfx.json

@@ -18,6 +18,7 @@
           "LICENSE-CODE",
           "ThirdPartyNotices.md",
           "SECURITY.md"
+          "lib/**"
         ]
       }
     ],

msal-javascript-conceptual/index.md

@@ -1 +1,12 @@
-# Welcome to msal-javascript-conceptual!
+---
+author: Dickson-Mwendia
+ms.service: active-directory
+ms.topic: include
+ms.date: 04/12/2023
+ms.author: dmwendia
+---
+
+# Welcome to msal-javascript-conceptual!
+
+
+J 

msal/docfx.json

@@ -44,8 +44,8 @@
         "files": [
           "**/*.md"
         ],
-        "src": "overview",
-        "dest": "api/overview",
+        "src": "msal",
+        "dest": "api",
         "exclude": [],
         "version": "msal-js-latest"
       },

msal/docs-ref-toc/fxtoc.yml

@@ -1,7 +1,11 @@
-- name: SDK reference
-  uid: msal.sdk.landingPage.reference
-  landingPageType: Root
+- name: MSAL.js Overview
   expanded: true
-  href: ~/overview/msal-overview.md
-  children:
-    - '**'
+  href: ~/msal/msal-overview.md
+- name: MSAL Browser
+  items:
+    - name: Initialization of MSAL
+      href: ~/msal/browser/initialization.md
+    - name: Sign in users
+      href: ~/msal/browser/login-user.md
+    - name: Acquire tokens
+      href: ~/msal/browser/acquire-token.md

msal/msal/browser/acquire-token.md

@@ -0,0 +1,16 @@
+---
+title: Acquire tokens in MSAL Browser
+description: Acquire tokens in MSAL Browser
+services: active-directory
+author: Dickson-Mwendia
+manager: CelesteDG
+
+ms.service: active-directory
+ms.subservice: develop
+ms.topic: reference
+ms.workload: identity
+ms.date: 04/12/2023
+ms.author: dmwendia
+---
+
+[!INCLUDE[MSAL Browser token acquisition](~/../lib/msal-browser/docs/includes/acquire-token.md)]

msal/msal/browser/initialization.md

@@ -0,0 +1,20 @@
+---
+title: MSAL Browser
+description:  Getting started with MSAL Browser
+services: active-directory
+author: Dickson-Mwendia
+manager: CelesteDG
+
+ms.service: active-directory
+ms.subservice: develop
+ms.topic: reference
+ms.workload: identity
+ms.date: 04/12/2023
+ms.author: dmwendia
+---
+
+
+# Getting started with MSAL Browser
+
+
+[!INCLUDE[MSAL Browser initialization](~/../../lib/msal-browser/docs/includes/initialization.md)]

msal/msal/browser/login-user.md

@@ -0,0 +1,16 @@
+---
+title: Sign in users in MSAL Browser
+description: Sign in users in MSAL Browser
+services: active-directory
+author: Dickson-Mwendia
+manager: CelesteDG
+
+ms.service: active-directory
+ms.subservice: develop
+ms.topic: reference
+ms.workload: identity
+ms.date: 04/12/2023
+ms.author: dmwendia
+---
+
+[!INCLUDE[Sign in users](msal-browser/docs/includes/login-user.md)]

msal/msal/browser/v1-migration.md

@@ -0,0 +1,127 @@
+# Migrating from MSAL 1.x to MSAL 2.x
+
+If you are new to MSAL, you should start [here](./initialization.md).
+
+If you are coming from [MSAL v1.x](../../msal-common/), you can follow this guide to update your code to use [MSAL v2.x](../../msal-browser/).
+
+## 1. Update application registration
+
+Go to the Azure AD portal for your tenant and review the App Registrations. You can create a [new registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#create-the-app-registration) for MSAL 2.x or you can [update your existing registration](https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-spa-app-registration#redirect-uri-msaljs-20-with-auth-code-flow) for the registration that you are using for MSAL 1.x.
+
+## 2. Add the msal-browser package to your project
+
+See the [installation section of the README](../README.md#installation).
+
+## 3. Update your code
+
+In MSAL 1.x, you created an application instance as below:
+
+```javascript
+import * as msal from "msal";
+
+const msalInstance = new msal.UserAgentApplication(config);
+```
+
+In MSAL 2.x, you can update this to use the new `PublicClientApplication` object.
+
+```javascript
+import * as msal from "@azure/msal-browser";
+
+const msalInstance = new msal.PublicClientApplication(config);
+```
+
+There may be some small differences in the configuration object that is passed in. If you are passing a more advanced configuration to the `UserAgentApplication` object, see [here](./configuration.md) for more information on new app object configuration options.
+
+Request and response object signatures have changed - `acquireTokenSilent` now has a separate object signature from the interactive APIs. Please see [here](./request-response-object.md) for more information on configuring the request APIs. 
+
+Most APIs from MSAL 1.x have been carried forward to MSAL 2.x without change. Some functions have been removed:
+- `handleRedirectCallback`
+- `urlContainsHash`
+- `getCurrentConfiguration`
+- `getLoginInProgress`
+- `getAccount`
+- `getAccountState`
+- `isCallback`
+
+In MSAL 2.x, handling the response from the hash is an asynchronous operation, as MSAL will perform a token exchange as soon as it parses the authorization code from the response. Because of this, when performing redirect calls, MSAL provides the `handleRedirectPromise` function which will return a promise that resolves when the redirect has been fully handled by MSAL. When using a redirect method, the page used as the `redirectUri` must implement  `handleRedirectPromise` to ensure the response is handled and tokens are cached when returning from the redirect.
+
+```javascript
+const myMSALObj = new msal.PublicClientApplication(msalConfig); 
+
+// Register Callbacks for Redirect flow
+myMSALObj.handleRedirectPromise().then((tokenResponse) => {
+    let accountObj = null;
+    if (tokenResponse !== null) {
+        accountObj = tokenResponse.account;
+        const id_token = tokenResponse.idToken;
+        const access_token = tokenResponse.accessToken;
+    } else {
+        const currentAccounts = myMSALObj.getAllAccounts();
+        if (!currentAccounts || currentAccounts.length === 0) {
+            // No user signed in
+            return;
+        } else if (currentAccounts.length > 1) {
+            // More than one user signed in, find desired user with getAccountByUsername(username)
+        } else {
+            accountObj = currentAccounts[0];
+        }
+    }
+
+    const username = accountObj.username;
+
+}).catch((error) => {
+    handleError(error);
+});
+
+function signIn() {
+    myMSALObj.loginRedirect(loginRequest);
+}
+
+async function getTokenRedirect(request) {
+    return await myMSALObj.acquireTokenSilent(request).catch(error => {
+        this.logger.info("silent token acquisition fails. acquiring token using redirect");
+        // fallback to interaction when silent call fails
+        return myMSALObj.acquireTokenRedirect(request)
+    });
+}
+```
+
+During `loginPopup`, `acquireTokenPopup`, or `acquireTokenSilent` calls, you can wait for the promise to resolve.
+
+```javascript
+const myMSALObj = new msal.PublicClientApplication(msalConfig); 
+
+async function signIn(method) {
+    try {
+        const loginResponse = await myMSALObj.loginPopup(loginRequest);
+    } catch (err) {
+        handleError(error);
+    }
+
+    const currentAccounts = myMSALObj.getAllAccounts();
+    if (!currentAccounts || currentAccounts.length === 0) {
+        // No user signed in
+        return;
+    } else if (currentAccounts.length > 1) {
+        // More than one user signed in, find desired user with getAccountByUsername(username)
+    } else {
+        accountObj = currentAccounts[0];
+    }
+}
+
+async function getTokenPopup(request) {
+    return await myMSALObj.acquireTokenSilent(request).catch(async (error) => {
+        this.logger.info("silent token acquisition fails. acquiring token using popup");
+        // fallback to interaction when silent call fails
+        return await myMSALObj.acquireTokenPopup(request).catch(error => {
+            handleError(error);
+        });
+    });
+}
+```
+
+Please see the [login](./login-user.md) and [acquire token](./acquire-token.md) docs for more detailed information on usage.
+
+Refresh tokens are now returned as part of the token responses, and are used by the library to renew access tokens without interaction or the use of iframes. See the [token lifetimes docs](./token-lifetimes.md) for more information on renewing tokens.
+
+All other APIs should work as before. It is recommended to take a look at the [default sample](../../../samples/msal-browser-samples/VanillaJSTestApp2.0) to see a working example of MSAL 2.0.

msal/msal/browser/v2-migration.md

@@ -0,0 +1,81 @@
+# Migrating from MSAL 2.x to MSAL 3.x
+
+If you are new to MSAL, you should start [here](initialization.md).
+
+If you are coming from [MSAL v1.x](../../msal-core/), you should check [this guide](v1-migration.md) first to migrate to [MSAL v2.x](../../msal-browser/) and then follow next steps.
+
+If you are coming from [MSAL v2.x](../../msal-browser/), you can follow this guide to update your code to use [MSAL v3.x](../../msal-browser/).
+
+## Update your code
+
+In MSAL v2.x, you created an application instance as below:
+
+```javascript
+import * as msal from "@azure/msal-browser";
+
+const msalConfig = {
+    auth: {
+        clientId: 'your_client_id'
+    }
+};
+
+const msalInstance = new msal.PublicClientApplication(msalConfig);
+```
+
+In MSAL v3.x, you must initialize the application object as well. There are several options at your disposal:
+
+### Option 1
+
+Instantiate a `PublicClientApplication` object and initialize it afterwards. The `initialize` function is asynchronous and must resolve before invoking other MSAL.js APIs.
+
+```javascript
+import * as msal from "@azure/msal-browser";
+
+const msalConfig = {
+    auth: {
+        clientId: 'your_client_id'
+    }
+};
+
+const msalInstance = new msal.PublicClientApplication(msalConfig);
+await msalInstance.initialize();
+```
+
+### Option 2
+
+Invoke the `createPublicClientApplication` static method which returns an initialized `PublicClientApplication` object. Note that this function is asynchronous.
+
+```javascript
+import * as msal from "@azure/msal-browser";
+
+const msalConfig = {
+    auth: {
+        clientId: 'your_client_id'
+    }
+};
+
+const msalInstance = await msal.PublicClientApplication.createPublicClientApplication(msalConfig);
+```
+
+All other APIs are backward compatible with [MSAL v2.x](../../msal-browser/). It is recommended to take a look at the [default sample](../../../samples/msal-browser-samples/VanillaJSTestApp2.0) to see a working example of MSAL v3.0.
+
+## Key changes
+
+### Browser support
+
+MSAL.js no longer supports the following browsers:
+
+- IE 11
+- Edge (Legacy)
+
+### Package dependencies
+
+Typescript version was bumped from `3.8.3` to `4.9.5`.
+
+### Compiler options
+
+Module/target versions were bumped from `es6`/`es5` to `es2020`/`es2020` respectively.
+
+### CDN
+
+MSAL.js is no longer hosted on a CDN. Check [this doc](cdn-usage.md) for more details.