Merge pull request #302158 from MicrosoftDocs/main

Merged by Learn.Build PR Management system

Author: learn-build-service-prod[bot]

articles/api-center/includes/api-center-portal-app-registration.md

@@ -35,7 +35,7 @@ If you want to create the app registration manually, follow these steps:
     1. Set **Name** to a meaningful name such as *api-center-portal*
     1. Under **Supported account types**, select **Accounts in this organizational directory (Single tenant)**. 
     1. In **Redirect URI**, select **Single-page application (SPA)** and set the URI. 
-        Enter the URI of your API Center portal deployment, in the following form: `https://<service-name>.portal.<location>.azure-api-center.ms`. Replace `<service name>` and `<location>` with the name of your API center and the location where it's deployed, Example: `https://myapicenter.portal.eastus.azure-api-center.ms`.
+        Enter the URI of your API Center portal deployment, in the following form: `https://<service-name>.portal.<location>.azure-apicenter.ms`. Replace `<service name>` and `<location>` with the name of your API center and the location where it's deployed, Example: `https://myapicenter.portal.eastus.azure-apicenter.ms`.
     1. Select **Register**.
 
 #### Configure additional redirect URIs for VS Code extension
@@ -49,4 +49,4 @@ When enabling the API Center portal view in the Visual Studio Code extension for
     `http://localhost`<br/>
     `ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>`<br/>
 
-    Replace `<application-client-id>` with the application (client) ID of this app. You can find this value on the **Overview** page of the app registration. 
+    Replace `<application-client-id>` with the application (client) ID of this app. You can find this value on the **Overview** page of the app registration. 

articles/api-center/set-up-api-center-portal.md

@@ -48,7 +48,7 @@ After you create the API Center portal app registration, you need to configure a
 You can now access the API Center portal:
 * On the **Portal settings** page, select **View API Center portal** to open the portal in a new tab. 
 * Or, enter the following URL in your browser, replacing `<service-name>` and `<location>` with the name of your API center and the location where it's deployed:<br/>
-    `https://<service-name>.portal.<location>.azure-api-center.ms`
+    `https://<service-name>.portal.<location>.azure-apicenter.ms`
 
 ### API visibility
 
@@ -96,4 +96,4 @@ To use AI-assisted search when signed in to the API Center portal, click in the
 
 ## Related content
 
-* [Enable and view Azure API Center portal in Visual Studio Code](enable-api-center-portal-vs-code-extension.md)
+* [Enable and view Azure API Center portal in Visual Studio Code](enable-api-center-portal-vs-code-extension.md)

articles/app-service/app-service-hybrid-connections.md

@@ -157,8 +157,8 @@ To install the Hybrid Connection Manager on Linux, from your terminal running as
 ```bash
 sudo apt update
 sudo apt install tar gzip build-essential
-wget "https://download.microsoft.com/download/HybridConnectionManager-Linux.tar.gz"
-tar -xf HybridConnectionManager-Linux.tar.gz
+sudo wget "https://download.microsoft.com/download/HybridConnectionManager-Linux.tar.gz"
+sudo tar -xf HybridConnectionManager-Linux.tar.gz
 cd HybridConnectionManager/
 sudo chmod 755 setup.sh
 sudo ./setup.sh

articles/app-service/configure-authentication-oauth-tokens.md

@@ -1,67 +1,43 @@
 ---
-title: Work with OAuth Tokens in AuthN/AuthZ
-description: Learn how to retrieve tokens, refresh tokens, and extend sessions when you use the built-in authentication and authorization in Azure App Service.
+title: Work with OAuth Tokens in Authentication and Authorization
+description: Learn how to retrieve, refresh, and extend session expiration for OAuth tokens when you use Azure App Service built-in authentication and authorization.
 ms.topic: how-to
-ms.date: 03/29/2021
+ms.date: 07/01/2025
 ms.custom: AppServiceIdentity
 author: cephalin
 ms.author: cephalin
 ---
 
-# Work with OAuth tokens in Azure App Service authentication
+# Manage OAuth tokens in Azure App Service
 
-This article shows you how to work with OAuth tokens when you use the built-in [authentication and authorization in Azure App Service](overview-authentication-authorization.md).
+This article shows you how to manage [OAuth](https://www.microsoft.com/security/business/security-101/what-is-oauth) tokens for [built-in authentication and authorization](overview-authentication-authorization.md) in Azure App Service.
 
 ## Retrieve tokens in app code
 
-From your server code, the provider-specific tokens are injected into the request header so that you can easily access them.
+Azure App Service injects your provider-specific tokens into the request header so you can easily access them. To get the provider-specific tokens, [token store](overview-authentication-authorization.md#token-store) must be enabled for the app.
 
-The following table lists possible token header names:
+Send an HTTP `GET` request to `/.auth/me` from your client code, such as a mobile app or in-browser JavaScript. The returned JSON has the provider-specific tokens.
+
+> [!NOTE]
+> Access tokens are for accessing provider resources, so are present only if you configure your provider with a client secret.
+
+The following table lists the OAuth token header names for several App Service built-in providers:
 
 | Provider | Header names |
 |-|-|
 | Microsoft Entra | `X-MS-TOKEN-AAD-ID-TOKEN` <br/> `X-MS-TOKEN-AAD-ACCESS-TOKEN` <br/> `X-MS-TOKEN-AAD-EXPIRES-ON`  <br/> `X-MS-TOKEN-AAD-REFRESH-TOKEN` |
-| Facebook Token | `X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN` <br/> `X-MS-TOKEN-FACEBOOK-EXPIRES-ON` |
+| Facebook | `X-MS-TOKEN-FACEBOOK-ACCESS-TOKEN` <br/> `X-MS-TOKEN-FACEBOOK-EXPIRES-ON` |
 | Google | `X-MS-TOKEN-GOOGLE-ID-TOKEN` <br/> `X-MS-TOKEN-GOOGLE-ACCESS-TOKEN` <br/> `X-MS-TOKEN-GOOGLE-EXPIRES-ON` <br/> `X-MS-TOKEN-GOOGLE-REFRESH-TOKEN` |
 | X | `X-MS-TOKEN-TWITTER-ACCESS-TOKEN` <br/> `X-MS-TOKEN-TWITTER-ACCESS-TOKEN-SECRET` |
 
 > [!NOTE]
-> Different language frameworks might present these headers to the app code in different formats, such as in lowercase or by using title case.
-
-From your client code (such as a mobile app or in-browser JavaScript), send an HTTP `GET` request to `/.auth/me` ([token store](overview-authentication-authorization.md#token-store) must be enabled). The returned JSON has the provider-specific tokens.
-
-> [!NOTE]
-> Access tokens are for accessing provider resources, so they're present only if you configure your provider with a client secret.
+> Different language frameworks might present these headers to the app code in different formats, such as lowercase or title case.
 
 ## Refresh auth tokens
 
-When your provider's access token (not the [session token](#extend-session-token-expiration-grace-period)) expires, you need to reauthenticate the user before you use that token again. You can avoid token expiration by making a `GET` call to the `/.auth/refresh` endpoint of your application. When called, App Service automatically refreshes the access tokens in the [token store](overview-authentication-authorization.md#token-store) for the authenticated user. Subsequent requests for tokens by your app code get the refreshed tokens. However, for token refresh to work, the token store must contain [refresh tokens](/entra/identity-platform/refresh-tokens) for your provider. The way to get refresh tokens is documented by each provider, but the following list is a brief summary:
-
-- **Google**: Append an `access_type=offline` query string parameter to your `/.auth/login/google` API call. For more information, see [Google Refresh Tokens](https://developers.google.com/identity/protocols/OpenIDConnect#refresh-tokens).
-- **Facebook**: Doesn't provide refresh tokens. Long-lived tokens expire in 60 days (see [Long-Lived Access Tokens](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/)).
-- **X**: Access tokens don't expire (see [OAuth FAQ](https://developer.x.com/en/docs/authentication/faq)).
-- **Microsoft**: In [https://resources.azure.com](https://resources.azure.com), do the following steps:
-    1. At the top of the pane, select **Read/Write**.
-    1. On the explorer menu, go to **subscriptions** > *subscription name* > **resourceGroups** > *resource group name* > **providers** > **Microsoft.Web** > **sites** > *app name* > **config** > **authsettingsV2**.
-    1. Select **Edit**.
-    1. Modify the following property:
-
-        ```json
-        "identityProviders": {
-          "azureActiveDirectory": {
-            "login": {
-              "loginParameters": ["scope=openid profile email offline_access"]
-            }
-          }
-        }
-        ```
-
-    1. Select **Put**.
+The following information refers to provider tokens. For session tokens, see [Extend session token expiration grace period](#extend-session-token-expiration-grace-period).
 
-    > [!NOTE]
-    > The scope that gives you a refresh token is [offline_access](../active-directory/develop/v2-permissions-and-consent.md#offline_access). See how it's used in [Tutorial: Authenticate and authorize users end to end in Azure App Service](tutorial-auth-aad.md). The other scopes are already requested by App Service by default. For information on these default scopes, see [OpenID Connect Scopes](../active-directory/develop/v2-permissions-and-consent.md#openid-connect-scopes).
-
-After your provider is configured, you can [find the refresh token and the expiration time for the access token](#retrieve-tokens-in-app-code) in the token store.
+If your provider's access token expires, you must reauthenticate the user before you can use that token again. You can avoid token expiration by making a `GET` call to the `/.auth/refresh` endpoint of your application.
 
 To refresh your access token at any time, call `/.auth/refresh` in any language. The following snippet uses jQuery to refresh your access tokens from a JavaScript client.
 
@@ -76,23 +52,48 @@ function refreshTokens() {
 }
 ```
 
-If a user revokes the permissions granted to your app, your call to `/.auth/me` might fail with a `403 Forbidden` response. To diagnose errors, check your application logs for details.
+When called, App Service automatically refreshes the access tokens in the [token store](overview-authentication-authorization.md#token-store) for the authenticated user. Subsequent requests for tokens get the refreshed tokens. You can see the refresh tokens and the expiration time for the tokens by using the headers listed in [Retrieve tokens in app code](#retrieve-tokens-in-app-code).
+
+>[!NOTE]
+>If a user revokes the permissions they granted to your app, your call to `/.auth/me` might fail with a `403 Forbidden` response. To diagnose errors, check your application logs for details.
+
+### Configure providers to supply refresh tokens
+
+For token refresh to work, the token store must contain [refresh tokens](/entra/identity-platform/refresh-tokens) from your provider. Each provider documents how to get their refresh tokens. The following table provides a brief summary:
+
+| Provider | Refresh tokens |
+|-|-|
+| Microsoft | Follow the procedure in [Configure the Microsoft Entra provider to supply refresh tokens](#configure-the-microsoft-entra-provider-to-supply-refresh-tokens). |
+| Facebook | Doesn't provide refresh tokens. Long-lived tokens expire in 60 days. For more information, see [Long-Lived Access Tokens](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/). |
+| Google | Append an `access_type=offline` query string parameter to your `/.auth/login/google` API call. For more information, see [Google Refresh Tokens](https://developers.google.com/identity/protocols/OpenIDConnect#refresh-tokens).|
+| X | Access tokens don't expire. For more information, see [OAuth FAQ](https://developer.x.com/en/docs/authentication/faq). |
+
+#### Configure the Microsoft Entra provider to supply refresh tokens
+
+1. In the Azure portal, go to the [API Playground (preview)](https://portal.azure.com/#view/Microsoft_Azure_Resources/ArmPlayground), and select **New request** if necessary.
+1. In the **Enter ARM relative path here including API version** field, enter the following string, replacing the placeholders with your subscription ID, resource group name, and app name:<br>`subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/sites/<app-name>/config/authsettingsV2?api-version=2024-11-01`
+1. Select **Execute**.
+1. Select `PUT` at upper left, and select the **Request body** tab.
+1. Copy the `GET` response contents from the **Response body** field and paste them into the **Request body** tab.
+1. In the code, locate the `"identityProviders":` **>** `"azureActiveDirectory":` **>** `"login":` section, and add the following line:<br>`"loginParameters": ["scope=openid profile email offline_access"]`
+1. Select **Execute**. The **Response body** field shows your changes.
+
+[Offline_access](/entra/identity-platform/scopes-oidc#the-offline_access-scope) is the scope that provides refresh tokens. App Service already requests the other scopes by default. For more information, see [OpenID Connect Scopes](/entra/identity-platform/scopes-oidc#openid-connect-scopes) and [Web Apps - Update Auth Settings V2](/rest/api/appservice/web-apps/update-auth-settings-v-2).
 
 ## Extend session token expiration grace period
 
-The authenticated session expires after 8 hours. After an authenticated session expires, a 72-hour grace period follows by default. Within this grace period, you're allowed to refresh the session token with App Service without reauthenticating the user. You can just call `/.auth/refresh` when your session token becomes invalid, and you don't need to track token expiration yourself. When the 72-hour grace period lapses, the user must sign in again to get a valid session token.
+The authenticated session expires after 8 hours, and a 72-hour default grace period follows. Within this grace period, you can refresh the session token with App Service without reauthenticating the user. You can simply call `/.auth/refresh` when your session token becomes invalid, and you don't need to track token expiration yourself.
 
-If 72 hours isn't enough time for you, you can extend this expiration window. Extending the expiration over a long period could have significant security implications (such as when an authentication token is leaked or stolen). We recommend that you leave the setting at the default 72 hours or set the extension period to the smallest value.
+When the 72-hour grace period lapses, the user must sign in again to get a valid session token. If you need a longer expiration window than 72 hours, you can extend it, but extending the expiration for a long period could have significant security implications if an authentication token is leaked or stolen. It's best to leave the setting at the default 72 hours or set the extension period to the smallest possible value.
 
-To extend the default expiration window, run the following command in [Azure Cloud Shell](../cloud-shell/overview.md).
+To extend the default expiration window, run the following Azure CLI command in [Azure Cloud Shell](../cloud-shell/overview.md):
 
 ```azurecli-interactive
 az webapp auth update --resource-group <group_name> --name <app_name> --token-refresh-extension-hours <hours>
 ```
 
 > [!NOTE]
-> The grace period only applies to the App Service authenticated session, not to the tokens from the identity providers. No grace period exists for expired provider tokens.
->
+> The grace period applies only to the App Service authenticated session, not to the access tokens from the identity providers. No grace period exists for expired provider tokens.
 
 ## Related content