Merge pull request #4939 from OfficeDev/main

[Admin] Publish

Author: ElizabethSamuel-MSFT

docs/develop/convert-xml-to-json-manifest.md

@@ -108,7 +108,7 @@ You can sideload the add-in using the Teams Toolkit or in a command prompt, bash
 
 1. First, *make sure Outlook desktop is closed.*
 1. Open a system prompt, bash shell, or the Visual Studio Code **TERMINAL**, and navigate to the root of the project.
-1. Run the command `npm run start:desktop`. The project builds and a Node dev-server window opens. This process may take a couple of minutes then Outlook desktop opens.
+1. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run `npm run start:desktop`; otherwise, run `npm run start`. The project builds and a Node dev-server window opens. This process may take a couple of minutes then Outlook desktop opens.
 1. You can now work with your add-in.
 1. When you're done working with your add-in, make sure to run the command `npm run stop`.
 
@@ -123,7 +123,7 @@ If the project was created with the Office Yeoman Generator and you don't want t
     ```
 
 1. Run `npm install`.
-1. To sideload the add-in, run `npm run start:desktop`. This command puts the unified manifest and the two image files into a zip file and sideloads it to the Office application. It also starts the server in a separate NodeJS window to host the add-in files on localhost.
+1. The command to sideload the add-in depends on when the project was created. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run `npm run start:desktop`; otherwise, run `npm run start`. This command puts the unified manifest and the two image files into a zip file and sideloads it to the Office application. It also starts the server in a separate NodeJS window to host the add-in files on localhost.
 
 When you're ready to stop the dev server and uninstall the add-in, run the command `npm run stop`.
 

docs/excel/custom-functions-debugging.md

@@ -70,9 +70,7 @@ If you aren't using VS Code, you can use the command line (such as bash, or Powe
 1. From the command line run `npm run watch` to watch for and rebuild when code changes occur.
 1. Open a second command line window (the first one will be blocked while running the watch.)
 
-1. If you want to start your add-in in the desktop version of Excel, run the following command.
-  
-    `npm run start:desktop`
+1. If you want to start your add-in in the desktop version of Excel and the "scripts" section of the project's package.json file has a "start:desktop" script, then run `npm run start:desktop`; otherwise, run `npm run start`.
 
     Or if you prefer to start your add-in in Excel on the web run the following command.
 
@@ -99,7 +97,7 @@ There are several build tasks available.
 
 You can use the following tasks to start debugging on desktop or online.
 
-- `npm run start:desktop`: Starts Excel on desktop and sideloads your add-in.
+- `npm run start:desktop`: Starts Excel on desktop and sideloads your add-in. If the "start:desktop" script isn't present in the "scripts" section of the project's package.json file, then run `npm run start` instead.
 - `npm run start:web -- --document {url}` (where `{url}` is the URL of an Excel file on OneDrive or SharePoint): Starts Excel on the web and sideloads your add-in.
 
   [!include[Mac command line note](../includes/mac-command-line.md)]

docs/outlook/autolaunch.md

@@ -94,7 +94,7 @@ Some Office.js APIs that change or alter the UI aren't allowed from event-based
 | API | Methods |
 | --- | --- |
 | `Office.devicePermission` | <ul><li>`requestPermissionsAsync`</li></ul> |
-| `Office.context.auth`\* | <ul><li>`getAccessToken`</li></ul><li>`getAccessTokenAsync`</li></ul> |
+| `Office.context.auth`\* | <ul><li>`getAccessToken`</li><li>`getAccessTokenAsync`</li></ul> |
 | `Office.context.mailbox` | <ul><li>`displayAppointmentForm`</li><li>`displayMessageForm`</li><li>`displayNewAppointmentForm`</li><li>`displayNewMessageForm`</li></ul> |
 | `Office.context.mailbox.item` | <ul><li>`close`</li></ul> |
 | `Office.context.ui` | <ul><li>`displayDialogAsync`</li><li>`messageParent`</li></ul>|

docs/outlook/faq-nested-app-auth-outlook-legacy-tokens.md

@@ -165,7 +165,7 @@ If you submit an issue, please include the following information.
 - Version of msal-browser.
 - Logs from msal-browser.
 
-## Developer troubleshooting questions
+## Developer questions
 
 ### How do I get more debug information from MSAL and NAA?
 
@@ -198,6 +198,24 @@ const msalConfig = {
 };
 ```
 
+### How do I validate the ID token or authenticate the user?
+
+Using Exchange tokens, you can validate the ID token and use it to authorize the user to access your own resources. For more information, see [Authenticate a user with an identity token for Exchange](authenticate-a-user-with-an-identity-token.md). However, MSAL with Entra ID tokens does not use this approach.
+
+When you request a token through MSAL, it always returns three tokens.
+
+|Token          |Purpose  |Scopes  |
+|---------------|---------|---------|
+|ID token | Provides information about the user to the client (task pane). | `profile` and `openid` |
+|Refresh token  | Refreshes the ID and access tokens when they expire.     | `offline_access`       |
+|Access token   | Authenticates the user for specific scopes to a resource, such as Microsoft Graph. | Any resource scopes, such as `user.read`. |
+
+Because MSAL always returns these tokens, it requests the `profile`, `openid`, and `offline_access` as default scopes even if your token request doesn't include them. However, you must have at least one resource scope, such as `user.read` so that you get an access token. If not, the request can fail. There isn't any way to use MSAL to only get an ID token. You always get all three tokens.
+
+Passing the ID token, or any of its claims, such as `oid` over a network call to a service is a security anti-pattern. The token is intended only for the client (task pane) and there is no way for the service to reliably use the token to be sure the user has authorized access. For more information about ID token claims, see [https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference](/entra/identity-platform/id-token-claims-reference).
+
+It's very important that you always request an access token to your own services. The access token also includes the same ID claims, so you don't need to pass the ID token. Instead create a custom scope for your service. For more information about app registration settings for your own services, see [Protected web API: App registration](/entra/identity-platform/scenario-protected-web-api-app-registration). When your service receives the access token, it can validate it, and use ID claims from inside the access token.
+
 ## Related content
 
 - [Enable SSO in an Office Add-in using nested app authentication](../develop/enable-nested-app-authentication-in-your-add-in.md).

docs/outlook/sideload-outlook-add-ins-for-testing.md

@@ -20,7 +20,7 @@ The process to sideload an add-in that uses the unified app manifest for Microso
 - For add-in projects created using the [Teams Toolkit](/microsoftteams/platform/toolkit/install-teams-toolkit?tabs=vscode), use one of the following options.
   - [Sideload in Visual Studio Code with Teams Toolkit](../develop/convert-xml-to-json-manifest.md#sideload-with-the-teams-toolkit)
   - [Sideload in Visual Studio Code with a system prompt, bash shell, or terminal](../develop/convert-xml-to-json-manifest.md#sideload-with-a-system-prompt-bash-shell-or-terminal)
-- For add-in projects created using the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md), in a command prompt, navigate to the root of your project. Then, run `npm run start:desktop`. The project builds and a Node dev-server window opens. This process may take a couple of minutes before it opens Outlook desktop.
+- For add-in projects created using the [Yeoman generator for Office Add-ins](../develop/yeoman-generator-overview.md), in a command prompt, navigate to the root of your project. Then, if there's a "start:desktop" script, run `npm run start:desktop`; otherwise, run `npm run start`. The project builds and a Node dev-server window opens. This process may take a couple of minutes before it opens Outlook desktop.
 - For NodeJS and npm projects that weren't created with the Yeoman generator, use one of the following options.
   - [Sideload with the Office-Addin-Debugging tool](../develop/convert-xml-to-json-manifest.md#sideload-with-the-office-addin-debugging-tool)
   - [Sideload with the Teams Toolkit CLI (command-line interface)](../develop/convert-xml-to-json-manifest.md#sideload-with-the-teams-toolkit-cli-command-line-interface)

docs/quickstarts/excel-custom-functions-quickstart.md

@@ -52,11 +52,7 @@ To test your add-in in Excel on the web, run the following command. When you run
 
 # [Excel on Windows or Mac](#tab/excel-windows)
 
-To test your add-in in Excel on Windows or Mac, run the following command. When you run this command, the local web server will start and Excel will open with your add-in loaded.
-
-```command line
-npm run start:desktop
-```
+The command to test your add-in in Excel on Windows or Mac depends on when the project was created. If there's a "start:desktop" script in the "scripts" section of the package.json file, then run `npm run start:desktop`; otherwise, run `npm run start`. The local web server will start and Excel will open with your add-in loaded.
 
 [!INCLUDE [alert use https](../includes/alert-use-https.md)]
 

docs/tutorials/excel-tutorial-create-custom-functions.md

@@ -58,11 +58,7 @@ In this tutorial, you will:
 
 # [Excel on Windows or Mac](#tab/excel-windows)
 
-To test your add-in in Excel on Windows or Mac, run the following command. When you run this command, the local web server will start and Excel will open with your add-in loaded.
-
-```command line
-npm run start:desktop
-```
+The command to test your add-in in Excel on Windows or Mac depends on when the project was created. If the "scripts" section of the project's package.json file has a "start:desktop" script, then run `npm run start:desktop`; otherwise, run the command `npm run start`. The local web server will start and Excel will open with your add-in loaded.
 
 [!INCLUDE [alert use https](../includes/alert-use-https.md)]