Merge pull request MicrosoftDocs#30 from cilwerner/consolidated-msal.js-docs

MSAL Node documentation updates

Author: cilwerner

msal-javascript-conceptual/node/accounts.md

@@ -5,7 +5,7 @@ author: EmLauber
 manager: CelesteDG
 ms.author: emilylauber
 
-ms.date: 04/26/2021
+ms.date: 10/26/2023
 ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
@@ -15,6 +15,12 @@ ms.reviewer: dmwendia,cwerner, owenrichards, kengaderdus
 
 # Accounts in MSAL Node
 
+This article shows you how to use the `msal-node` library to access cached accounts in your Node.js application. The APIs, `getAllAccounts()`, `getAccountByHomeId()`, and `getAccountByLocalId()` are covered 
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/en/download/)
+
 ## Usage
 
 The `msal-node` library provides the following different APIs to access cached accounts:
@@ -25,7 +31,7 @@ The `msal-node` library provides the following different APIs to access cached a
 
 The following are usage examples for each API:
 
-### getAllAccounts
+### `getAllAccounts`
 
 For a multiple accounts scenario:
 
@@ -57,7 +63,7 @@ function callAcquireTokenSilent()
 });
 ```
 
-### getAccountByHomeId and getAccountByLocalId
+### `getAccountByHomeId` and `getAccountByLocalId`
 
 For a single account scenario, the `homeAccountId` or `localAccountId` must be obtained from the initial `AuthResponse` object received from a non-silent authorization flow, such as the `Auth Code` flow.
 
@@ -113,7 +119,8 @@ async function getResource() {
 }
 ```
 
-## Notes
+For a multiple accounts scenario, please should modify the [sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/samples/msal-node-samples/silent-flow/index.js) (in `/graphCall` route) to list all cached accounts and choose a specific account. You may also need to customize the related view templates and `handlebars` template params.
+
+## See also
 
-* The current msal-node silent-flow [sample](../../../samples/msal-node-samples/silent-flow) has a working single account scenario that uses `getAccountByHomeId()`.
-* If you have a multiple accounts scenario, please modify the [sample](../../../samples/msal-node-samples/silent-flow/index.js) (in `/graphCall` route) to list all cached accounts and choose a specific account. You may also need to customize the related view templates and `handlebars` template params.
+* The current msal-node silent-flow [sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/silent-flow) has a working single account scenario that uses `getAccountByHomeId()`.

msal-javascript-conceptual/node/brokering.md

@@ -1,11 +1,11 @@
 ---
 title: "Acquiring Device Bound Tokens"
-description: Learn how to acquire tokens from the native token broker.
+description: Learn how to acquire device bound tokens from the native token broker.
 author: EmLauber
 manager: CelesteDG
 ms.author: emilylauber
 
-ms.date: 04/26/2021
+ms.date: 10/26/2023
 ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
@@ -15,11 +15,7 @@ ms.reviewer: dmwendia,cwerner, owenrichards, kengaderdus
 
 # Acquiring Device Bound Tokens
 
-MSAL Node supports acquiring tokens from the native token broker. When using the native broker refresh tokens are bound to the device on which they are acquired on and are not accessible by `msal-node` or the application. This provides a higher level of security that cannot be achieved by `msal-node` alone.
-
-## Supported Environment
-
-This feature is currently only supported on Windows.
+MSAL Node supports acquiring tokens from the native token broker. When using the native broker refresh tokens are bound to the device on which they are acquired on and are not accessible by `msal-node` or the application. This provides a higher level of security that cannot be achieved by `msal-node` alone. This feature is currently only supported on Windows.
 
 ## Prerequisites
 
@@ -46,9 +42,9 @@ const msalConfig: Configuration = {
 const pca = new PublicClientApplication(msalConfig);
 ```
 
-Please note that `msal-node` will _not_ fallback to the non-brokered flow in the event of a failure. In order to avoid unexpected failures in the future, only enable the broker flow in environments which support it (refer to the [Supported Environment](#supported-environment) section above).
+Please note that `msal-node` will _not_ fallback to the non-brokered flow in the event of a failure. In order to avoid unexpected failures in the future, only enable the broker flow in environments which support it.
 
-A working sample can be found [here](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-cli-brokered-app)
+A working sample can be found in the [auth-code-cli-brokered-app sample](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-cli-brokered-app)
 
 ## Window Parenting
 

msal-javascript-conceptual/node/MIP-caching.md renamed to msal-javascript-conceptual/node/caching-in-extensions.md

@@ -1,18 +1,18 @@
 ---
-title: "Microsoft Authentication Extensions for Node"
+title: Caching in Microsoft Authentication Extensions for Node
 description: The Microsoft Authentication Extensions for Node enables application developers to perform cross-platform token cache serialization and persistence. It gives extra support to the Microsoft Authentication Library for Node (MSAL Node).
 author: henrymbuguakiarie
 manager: CelesteDG
 ms.author: henrymbugua
-ms.date: 02/04/2022
+ms.date: 10/04/2023
 ms.reviewer: j-mantu, samuelkubai, Dickson-Mwendia
 ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
 #Customer intent: As an application developer, I want to learn how to use the Microsoft Authentication Extensions for Node to perform cross-platform token cache serialization and persistence.
 ---
 
-# Microsoft Authentication Extensions for Node
+# Caching in Microsoft Authentication Extensions for Node
 
 The Microsoft Authentication Extensions for Node enables developers to perform cross-platform token cache serialization and persistence to disk. It gives extra support to the Microsoft Authentication Library (MSAL) for Node.
 
@@ -91,9 +91,3 @@ The following table provides an explanation for all the arguments for the persis
 | accountName             | Specifies the account name to be used on Mac and/or Linux                                      | Mac and Linux          |
 | usePlaintextFileOnLinux | The flag to default to plain text on linux if LibSecret fails. Defaults to `false`            | Linux                  |
 
-## Next steps
-
-For more information about Microsoft Authentication Extensions for Node and MSAL Node, see:
-
-- [Microsoft Authentication Extensions for Node](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/extensions/msal-node-extensions)
-- [Microsoft Authentication Library for Node](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node)

msal-javascript-conceptual/node/caching.md

@@ -5,7 +5,7 @@ author: EmLauber
 manager: CelesteDG
 ms.author: emilylauber
 
-ms.date: 04/26/2021
+ms.date: 04/26/2023
 ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
@@ -17,11 +17,11 @@ ms.reviewer: dmwendia, cwerner, owenrichards, kengaderdus
 
 When MSAL Node acquires a token, it caches it in memory for future usage. MSAL Node manages the token lifetime and refreshing for you. APIs like `acquireTokenSilent()` retrieves access tokens from the cache for a given account:
 
-> :information_source: MSAL does not expose refresh tokens for security reasons. See [FAQ: How do I get the Refresh Token](./faq.md#how-do-i-get-the-refresh-token) for more.
+MSAL does not expose refresh tokens for security reasons. Refer to the [FAQ](./faq.md#how-do-i-get-the-refresh-token) for how to get the refresh tokens.
 
-### Using secrets securely
+## Use client secrets securely
 
-Secrets should never be hardcoded. The dotenv npm package can be used to store secrets in a .env file (located in project's root directory) that should be included in .gitignore to prevent accidental uploads of the secrets.
+Client secrets should never be hardcoded. The dotenv npm package can be used to store secrets in a *.env* file (located in project's root directory) that should be included in *.gitignore* to prevent accidental uploads of the secrets.
 
 ```javascript
 const msal = require('@azure/msal-node');
@@ -39,7 +39,6 @@ const cca = new msal.ConfidentialClientApplication({
 /**
 * acquireToken* APIs return an account object containing the "homeAccountId"
 * you should keep a record of this in your app and use it later on when calling acquireTokenSilent
-* For more, see: https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/accounts.md
 */
 const someUserHomeAccountId = "Enter_User_Home_Account_Id";
 
@@ -58,10 +57,10 @@ cca.acquireTokenSilent(silentTokenRequest).then((response) => {
 });
 ```
 
-In production, you would most likely want to serialize and persist the token cache. Depending on the type of application, you can:
+In production, you'd most likely want to serialize and persist the token cache. Depending on the type of application, you can:
 
 * Desktop apps, console apps (public clients apps (PCA)):
-  * Use [MSAL Node Extensions](../../../extensions/msal-node-extensions/README.md), which provides persistence and encryption at rest solutions on Windows, Linux and Mac OS
+  * Use [MSAL Node Extensions](./extensions.md), which provides persistence and encryption at rest solutions on Windows, Linux and Mac OS
 * Web apps, web APIs, daemon apps (confidential client apps (CCA)):
   * MSAL's in-memory token cache does not scale for production. Use the [distributed token caching](#performance-and-security) pattern to persist the cache in your choice of storage environment (Redis, MongoDB, SQL databases etc. -keep in mind that you can use these in tandem *e.g.* a Redis-like memory cache as a first layer of persistence, and a SQL database as a second, more stable persistence layer)
 
@@ -71,16 +70,16 @@ MSAL maintains an in-memory cache. The in-memory cache is representative of the
 
 Note that the in-memory cache is not scalable for server-side applications and performance will degrade after holding a few 100 tokens in cache. For web app and web API scenarios, this approximates to serving a few 100 users. For daemon app scenarios using client credentials grant to call other apps, this means a few 100 tenants. See [performance](#performance-and-security) below for more.
 
-> :warning: We recommend **persisting** the cache with **encryption** for all production applications both for security and desired cache longevity. If you choose not to persist the cache, the [TokenCache](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_node.tokencache.html) interface is still available to access the cached entities.
+> :warning: We recommend **persisting** the cache with **encryption** for all production applications both for security and desired cache longevity. If you choose not to persist the cache, the [TokenCache](/javascript/api/@azure/msal-node/tokencache) interface is still available to access the cached entities.
 
 ## Persistent cache
 
-MSAL Node fires events when the in-memory cache is accessed and apps can choose whether to persist the cache (see: [TokenCacheContext](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_common.tokencachecontext.html)) (e.g. to a file, a SQL database and etc.). This constitutes two actions:
+MSAL Node fires events when the in-memory cache is accessed and apps can choose whether to persist the cache (see: [TokenCacheContext](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_node.TokenCacheContext.html)) (e.g. to a file, a SQL database and etc.). This constitutes two actions:
 
 1. Load the cache from persistence to MSAL's memory before accessing the cache
 2. If the in-memory cache has changed since last access, save the cache back to persistence
 
-For persisting the cache, MSAL accepts a custom cache plugin in [configuration](./configuration.md). This plugin should implement the [ICachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_common.icacheplugin.html) interface:
+For persisting the cache, MSAL accepts a custom cache plugin in [configuration](./configuration.md). This plugin should implement the [ICachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.ICachePlugin.html) interface:
 
 ```typescript
 interface ICachePlugin {
@@ -112,14 +111,14 @@ class MyCachePlugin implements ICachePlugin {
 }
 ```
 
-* If you are developing a public client app, [MSAL Node Extensions](../../../extensions/msal-node-extensions/README.md) handles this for you.
+* If you are developing a public client app, [MSAL Node Extensions](./extensions.md) handles this for you.
 * If you are developing a confidential client app, you should persist the cache via a separate service, since a single, *per-server* cache instance isn't suitable for a cloud environment with many servers and app instances.
 
-> :warning: We strongly recommend to encrypt the token cache when persisting it on disk. For public client apps, this is offered out-of-box with [MSAL Node Extensions](../../../extensions/msal-node-extensions/README.md). For confidential clients however, you are responsible for devising an appropriate encryption solution.
+We strongly recommend to encrypt the token cache when persisting it on disk. For public client apps, this is offered out-of-box with MSAL Node Extensions. For confidential clients however, you are responsible for devising an appropriate encryption solution.
 
 ## Performance and security
 
-On public client apps, [MSAL Node Extensions](../../../extensions/msal-node-extensions/README.md) ensures performance and security for you.
+On public client apps, MSAL Node Extensions ensures performance and security for you.
 
 On confidential client apps that handle users (web apps that sign in users and call web APIs, and web APIs calling downstream web APIs), there can be many users active concurrently for a given application. Our recommendation is to serialize one cache blob (see [CacheRecord](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-common/src/cache/entities/CacheRecord.ts)) per user. This would help with scaling the cache across a distributed system. Use a key for partitioning the cache (*i.e.* **partition key**), such as:
 
@@ -131,19 +130,17 @@ On confidential client apps that handle users (web apps that sign in users and c
 
 ### Web apps
 
-Since web apps are user-facing and often rely on sessions to keep track of each user, the appropriate partition key for caching is often stored within the session data, and needs to be retrieved before the cache lookup can take place. To help with this, MSAL Node provides the [DistributedCachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/classes/_azure_msal_node.distributedcacheplugin.html) class, which implements the [ICachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_common.icacheplugin.html). An instance of `DistributedCachePlugin` requires:
+Since web apps are user-facing and often rely on sessions to keep track of each user, the appropriate partition key for caching is often stored within the session data, and needs to be retrieved before the cache lookup can take place. To help with this, MSAL Node provides the [DistributedCachePlugin](/javascript/api/@azure/msal-node/distributedcacheplugin) class, which implements the [ICachePlugin](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.ICachePlugin.html). An instance of `DistributedCachePlugin` requires:
 
-* a **client interface** ([ICacheClient](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.icacheclient.html)), which implements `get` and `set` operations on the persistence server (Redis, MySQL etc.).
-* a **partition manager** ([IPartitionManager](https://azuread.github.io/microsoft-authentication-library-for-js/ref/interfaces/_azure_msal_node.ipartitionmanager.html)), for reading from and writing to cache with respect to a given **session ID**.
+* a **client interface** ([ICacheClient](/javascript/api/@azure/msal-node/icacheclient)), which implements `get` and `set` operations on the persistence server (Redis, MySQL etc.).
+* a **partition manager** ([IPartitionManager](/javascript/api/@azure/msal-node/ipartitionmanager)), for reading from and writing to cache with respect to a given **session ID**.
 
-Please refer to the [Web app using DistributedCachePlugin](../../../samples/msal-node-samples/auth-code-distributed-cache/README.md) for a sample implementation.
+Please refer to the [Web app using DistributedCachePlugin](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-distributed-cache) for a sample implementation.
 
-## More information
+## See also
 
 See the samples below for more about how to handle caching in MSAL Node apps:
 
-* [(PCA) Console app using MSAL Node Extensions](../../../extensions/samples/msal-node-extensions/index.js)
-* [(PCA) Dektop app using MSAL Node Extensions](../../../extensions/samples/electron-webpack/README.md)
-* [(CCA) Web app using DistributedCachePlugin](../../../samples/msal-node-samples/auth-code-distributed-cache/README.md)
-* [(CCA) Web API using a custom distributed cache plugin](../../../samples/msal-node-samples/auth-code-distributed-cache/README.md)
-* [(CCA) Daemon app using a custom distributed cache plugin](../../../samples/msal-node-samples/auth-code-distributed-cache/README.md)
+* [(PCA) Console app using MSAL Node Extensions](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/extensions/samples/msal-node-extensions/index.js)
+* [(PCA) Dektop app using MSAL Node Extensions](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/extensions/samples/electron-webpack)
+* [(CCA) Web app using DistributedCachePlugin](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code-distributed-cache)