Merge pull request #301995 from v-thepet/app10

Stacyrch140 · web-flow · commit 6e6029a53349 · 2025-07-02T11:56:42.000-04:00
Freshness: Azure App Service 10
diff --git a/articles/app-service/deploy-configure-credentials.md b/articles/app-service/deploy-configure-credentials.md
@@ -1,134 +1,166 @@
 ---
-title: Configure Deployment Credentials
-description: Learn what types of deployment credentials are in Azure App Service and how to configure and use them.
+title: Manage Deployment Credentials
+description: Learn about the types of deployment credentials for deploying local apps to Azure App Service and how to configure and use them.
 author: cephalin
 ms.author: cephalin
 ms.reviewer: byvinyal
 ms.topic: how-to
-ms.date: 01/26/2024
+ms.date: 07/01/2025
 
 ---
 
-# Configure deployment credentials for Azure App Service
-To secure app deployment from a local computer, [Azure App Service](./overview.md) supports two types of credentials for [local Git deployment](deploy-local-git.md) and [FTP/FTPS deployment](deploy-ftp.md). These credentials are different from your Azure subscription credentials.
+# Manage deployment credentials for Azure App Service
+
+You can deploy local apps to [Azure App Service](overview.md) by using [local Git deployment](deploy-local-git.md) or [FTP/S deployment](deploy-ftp.md). This article explains how to create and manage deployment credentials for local Git or FTP/S deployment.
+
+Deployment credentials are different from your Azure subscription credentials. App Service supports two types of credentials for secure local app deployment: *user-scope* and *app-scope* credentials.
 
 [!INCLUDE [app-service-deploy-credentials](../../includes/app-service-deploy-credentials.md)]
 
-> [!NOTE]
-> When [basic authentication is disabled](configure-basic-auth-disable.md), you can't view or configure deployment credentials in **Deployment Center**.
+## Prerequisites
 
-## <a name="userscope"></a>Configure user-scope credentials
+To set, reset, access, or use deployment credentials, you must have **Contributor**-level permissions on the App Service app.
 
-# [Azure CLI](#tab/cli)
+<a name="disable-basic-authentication"></a>
+### Basic authentication requirement
 
-Run the [`az webapp deployment user set`](/cli/azure/webapp/deployment/user#az-webapp-deployment-user-set) command. Replace `<username>` and `<password>` with a deployment user's username and password.
+To publish App Service apps via local Git or FTP/S, you must enable basic authentication. **SCM Basic Auth Publishing Credentials** and **FTP Basic Auth Publishing Credentials** must both be set to **On** on the app's **Configuration** page in the Azure portal.
 
-- The username must be unique within Azure, and for local Git pushes, must not contain the @ symbol.
-- The password must be at least eight characters long, with two of the following three elements: letters, numbers, and symbols.
+Basic authentication is less secure than other authentication methods and is disabled by default for new apps. If basic authentication is disabled, you can't view or set deployment credentials in the app's **Deployment Center** or use these credentials for publishing. For more information, see [Disable basic authentication in Azure App Service deployments](configure-basic-auth-disable.md).
 
-```azurecli-interactive
-az webapp deployment user set --user-name <username> --password <password>
-```
+<a name="userscope"></a>
+## Set user-scope credentials
 
-The JSON output shows the password as `null`.
+For FTP/S deployment, you need both a user name and a password. Local Git deployment requires only a user name. The user name must be unique within Azure.
 
-# [Azure PowerShell](#tab/powershell)
+For local Git deployment, the user name can't contain the `@` character.
 
-You can't configure the user-scope credentials by using Azure PowerShell. Use a different method, or consider [using application-scope credentials](#appscope).
+For FTP/S deployment:
 
-# [Azure portal](#tab/portal)
+- The user name must follow the format `<app-name>\<user-name>`. Since user-scope credentials are linked to the user and not to the app, this format directs the sign-in action to the correct FTP/S endpoint for the app.
 
-You can configure your user-scope credentials in any app's [resource page](../azure-resource-manager/management/manage-resources-portal.md#manage-resources). Regardless of which app you use to configure these credentials, the credentials apply to all apps for all subscriptions in your Azure account.
+- The password must be at least eight characters and contain capital letters, lowercase letters, numbers, and symbols. The Azure portal doesn't show the user-scope password, and the JSON output shows it as `null`. If you lose or forget your password, you can [reset your credentials](#reset-credentials) to get a new one.
 
- You must have at least one app in the [Azure portal](https://portal.azure.com) before you can access the deployment credentials page. To configure your user-scope credentials:
+You can configure user-scope credentials by using Azure CLI or the Azure portal.
 
-1. From the left menu of your app, select > **Deployment Center** > **FTPS credentials** or **Local Git/FTPS credentials**.
+# [Azure CLI](#tab/cli)
 
-2. Scroll down to **User scope**, configure the **Username** and **Password**, and then select **Save**.
+To create user-scope credentials using Azure CLI, run the [`az webapp deployment user set`](/cli/azure/webapp/deployment/user#az-webapp-deployment-user-set) command, replacing `<username>` and `<password>` with values you select.
 
-After you set your deployment credentials, you can find the Git deployment username in your app's **Overview** page.
+```azurecli-interactive
+az webapp deployment user set --user-name <username> --password <password>
+```
 
-![Screenshot that shows you how to find the Git deployment user name on your app's Overview page.](./media/app-service-deployment-credentials/deployment_credentials_overview.png)
+# [Azure PowerShell](#tab/powershell)
 
-If Git deployment is configured, the page shows **Git/deployment username**. Otherwise, it shows **FTP/deployment username**.
+You can't create user-scope credentials by using Azure PowerShell. Use Azure CLI or the Azure portal to create the credentials, or use app-scope credentials to deploy to FTP/S or local Git.
 
-> [!NOTE]
-> Azure doesn't show your user-scope deployment password. If you forget the password, you can follow the steps in this section to reset your credentials.
+# [Azure portal](#tab/portal)
+
+In the [Azure portal](https://portal.azure.com), you must have at least one app to use for setting user-scope credentials. The credentials then apply to all apps for all subscriptions in your Azure account that have **SCM Basic Auth** and **FTP Basic Auth** enabled.
+
+1. Select **Deployment Center** under **Deployment** in the left navigation menu of an app.
+1. Select the **FTPS credentials** tab, or if **Local Git** is configured as the build source, the **Local Git/FTPS credentials** tab.
+1. In the **User-scope** section, add a **Username**.
+1. Add and confirm a **Password**.
+1. Select **Save**.
 
 -----
 
-## Use user-scope credentials with FTP/FTPS
+After you set user-scope credentials, you can see your deployment user name on your app's **Overview** page in the Azure portal. If local Git deployment is configured, the label is **Git/Deployment username**. Otherwise, the label is **FTP/Deployment username**.
+
+![Screenshot that shows the Git deployment user name on an app's Overview page.](./media/app-service-deployment-credentials/deployment_credentials_overview.png)
+
+<a name="appscope"></a>
+## Get application-scope credentials
 
-To authenticate to an FTP/FTPS endpoint by using user-scope credentials, your username must follow this format:
-`<app-name>\<user-name>`
+The application-scope credentials are automatically created at app creation. The FTP/S app-scope user name always follows the format `app-name\$app-name`. The local Git app-scope user name uses the format `$app-name`.
 
-Since user-scope credentials are linked to the user and not to a specific resource, the username must be in this format to direct the sign-in action to the right app endpoint.
+>[!NOTE]
+>When you use `git remote add` in shells that use the dollar sign for variable interpolation, such as Bash, you must use `\$` to escape any dollar signs in the username or password to avoid authentication errors.
 
-## <a name="appscope"></a>Get application-scope credentials
+You can get your app-scope credentials by using Azure CLI, Azure PowerShell, or the Azure portal.
 
 # [Azure CLI](#tab/cli)
 
-Get the application-scope credentials by using the [`az webapp deployment list-publishing-profiles`](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-profiles) command. For example:
+In Azure CLI, get the application-scope credentials by using the [`az webapp deployment list-publishing-profiles`](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-profiles) command. For example:
 
 ```azurecli-interactive
-az webapp deployment list-publishing-profiles --resource-group <group-name> --name <app-name>
+az webapp deployment list-publishing-profiles --resource-group myResourceGroup --name myApp
 ```
 
-For [local Git deployment](deploy-local-git.md), you can also use the [`az webapp deployment list-publishing-credentials`](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-credentials) command. When you use this command, you get a Git remote URI for your app that has the application-scope credentials already embedded. For example:
+For [local Git deployment](deploy-local-git.md), you can also use the [`az webapp deployment list-publishing-credentials`](/cli/azure/webapp/deployment#az-webapp-deployment-list-publishing-credentials) command. The following example returns a Git remote URI that has the application-scope credentials for the app already embedded.
 
 ```azurecli-interactive
-az webapp deployment list-publishing-credentials --resource-group <group-name> --name <app-name> --query scmUri
+az webapp deployment list-publishing-credentials --resource-group myResourceGroup --name myApp --query scmUri
 ```
 
-> [!NOTE]
-> The returned Git remote URI doesn't contain `/<app-name>.git` at the end. When you add the remote URI, make sure to append `/<app-name>.git` to avoid an error 22 with `git-http-push`. Additionally, when using `git remote add ... ` via shells that use the dollar sign for variable interpolation (such as bash), escape any dollar signs `\$` in the username or password. Failure to escape this character can result in authentication errors.
+The returned Git remote URI doesn't have `/<app-name>.git` at the end. If you use the URI to add a remote, append `/<app-name>.git` to the URI to avoid an error `22` with `git-http-push`.
 
 # [Azure PowerShell](#tab/powershell)
 
-Get the application-scope credentials by using the [`Get-AzWebAppPublishingProfile`](/powershell/module/az.websites/get-azwebapppublishingprofile) command. For example:
+In Azure PowerShell, get the application-scope credentials by using the [`Get-AzWebAppPublishingProfile`](/powershell/module/az.websites/get-azwebapppublishingprofile) command. For example:
 
 ```azurepowershell-interactive
-Get-AzWebAppPublishingProfile -ResourceGroupName <group-name> -Name <app-name>
+Get-AzWebAppPublishingProfile -ResourceGroupName myResourceGroup -Name myApp
 ```
 
 # [Azure portal](#tab/portal)
 
-1. From the left menu of your app, select **Deployment Center** > **FTPS credentials** or **Local Git/FTPS credentials**.
+To get the application-scope credentials in the Azure portal:
 
-2. In the **Application scope** section, select the **Copy** link to copy the username or password.
+1. Select **Deployment Center** under **Deployment** in the left navigation menu of your app.
+1. On the **Deployment Center** page, select the **FTPS credentials** or **Local Git/FTPS credentials** tab.
+1. In the **Application-scope** section, view the **FTPS username**, **Local Git username**, and **Password**. Select the copy icons to copy the values.
 
 -----
 
-## Reset application-scope credentials
+## Reset credentials
+
+You can use Azure CLI, Azure PowerShell, or the Azure portal to reset your application-scope deployment credentials and get a new password. The app-scope user names retain their autogenerated values.
+
+In Azure CLI and the Azure portal, you can also reset your user-scope credentials by creating new ones. This action affects all the apps in your account that use the user-scope credentials.
+
+When you reset your deployment credentials, any external integrations and automation via the publishing profile stop working and must be reconfigured with the new values.
 
 # [Azure CLI](#tab/cli)
 
-Reset the application-scope credentials by using the [`az resource invoke-action`](/cli/azure/resource#az-resource-invoke-action) command:
+In Azure CLI, reset the application-scope password by using the [`az resource invoke-action`](/cli/azure/resource#az-resource-invoke-action) command with the `newpassword` action.
 
 ```azurecli-interactive
 az resource invoke-action --action newpassword --resource-group <group-name> --name <app-name> --resource-type Microsoft.Web/sites
 ```
 
+Reset the user-scope credentials by rerunning the [`az webapp deployment user set`](/cli/azure/webapp/deployment/user#az-webapp-deployment-user-set) command to create new user name and password values.
+
+```azurecli-interactive
+az webapp deployment user set --user-name <new-username> --password <new-password>
+```
+
 # [Azure PowerShell](#tab/powershell)
 
-Reset the application-scope credentials by using the [`Invoke-AzResourceAction`](/powershell/module/az.resources/invoke-azresourceaction) command:
+In Azure PowerShell, reset the application-scope password by using the [`Invoke-AzResourceAction`](/powershell/module/az.resources/invoke-azresourceaction) command with the `newpassword` action:
 
 ```azurepowershell-interactive
 Invoke-AzResourceAction -ResourceGroupName <group-name> -ResourceType Microsoft.Web/sites -ResourceName <app-name> -Action newpassword
 ```
 
 # [Azure portal](#tab/portal)
 
-1. From the left menu of your app, select **Deployment Center** > **FTPS credentials** or **Local Git/FTPS credentials**.
+In the Azure portal, select **Deployment Center** from your app's left navigation menu, and then select the **FTPS credentials** or **Local Git/FTPS credentials** tab.
 
-2. In the **Application scope** section, select **Reset**.
+- To reset your app-scope credentials and get a new password, select **Reset** at the bottom of the **Application-scope** section.
 
------
+- To reset your user-scope credentials:
+  1. Select **Reset** at the bottom of the **User-scope** section. This selection deletes both user name and password, and disables user-scope credentials.
+  1. To reset and reenable your user-scope credentials, enter a new username and password, and select **Save**.
 
-## Disable basic authentication
+This action takes effect across all the apps in your account that use the user-scope credentials.
 
-See [Disable basic authentication in App Service deployment](configure-basic-auth-disable.md).
+-----
 
 ## Related content
 
-Find out how to use these credentials to deploy your app from a [local Git](deploy-local-git.md) or by using [FTP/FTPS](deploy-ftp.md).
+- [Disable basic authentication in Azure App Service deployments](configure-basic-auth-disable.md)
+- [Deploy to Azure App Service by using local Git](deploy-local-git.md)
+- [Deploy your app to Azure App Service using FTP/S](deploy-ftp.md)
diff --git a/articles/app-service/media/app-service-deployment-credentials/deployment_credentials_overview.png b/articles/app-service/media/app-service-deployment-credentials/deployment_credentials_overview.png
diff --git a/includes/app-service-deploy-credentials.md b/includes/app-service-deploy-credentials.md
@@ -2,11 +2,14 @@
 author: cephalin
 ms.service: azure-app-service
 ms.topic: include
-ms.date: 04/20/2020
+ms.date: 06/30/2025
 ms.author: cephalin
 ---
 
-* **User-level credentials**: One set of credentials for the entire Azure account. These credentials can be used to deploy to App Service for any app in any subscription that the Azure account has permission to access. This credentials set is the default that surfaces in the portal's graphical environment, like in **Overview** and **Properties**
-on the app's [resource pane](/azure/azure-resource-manager/management/manage-resources-portal#manage-resources). When a user is granted app access via role-based access control (RBAC) or coadministrator permissions, they can use their user-level credentials until access is revoked. Don't share these credentials with other Azure users.
+- **User-scope** or user-level credentials provide one set of deployment credentials for a user's entire Azure account. A user who is granted app access via role-based access control (RBAC) or coadministrator permissions can use their user-level credentials as long as they have those permissions.
 
-* **App-level credentials**: One set of credentials for each app. These credentials can be used to deploy to that app only. The credentials for each app are generated automatically at app creation. They can't be configured manually, but can be reset anytime. To grant a user access to app-level credentials via RBAC, that user must have **Contributor** level or higher permissions on the app (including the built-in **Website Contributor** role). Readers aren't allowed to publish, and can't access those credentials.
+  You can use your user-scope credentials to deploy any app to App Service via local Git or FTP/S in any subscription that your Azure account has permission to access. You don't share these credentials with any other Azure users. You can reset your user-scope credentials anytime.
+
+- **App-scope** or application-level credentials are one set of credentials per app that can be used to deploy that app only. These credentials are generated automatically for each app at creation and can't be configured manually, but the password can be reset anytime.
+
+  A user must have at least **Contributor** level permissions on an app, including the built-in **Website Contributor** role, to be granted access to app-level credentials via RBAC. **Reader** role can't publish and can't access these credentials.
