Differences
This shows you the differences between the selected revisions of the page.
| private_playground 2026-05-21 | private_playground 2026-06-02 (current) | ||
| Line 1: | Line 1: | ||
| ~~NOINDEX~~ | ~~NOINDEX~~ | ||
| ====== Connecting securely to Microsoft Azure Storage with SFTP ====== | ====== Connecting securely to Microsoft Azure Storage with SFTP ====== | ||
| - | With WinSCP you can easily upload and manage files on your Microsoft Azure Storage account contained with [[sftp|SFTP protocol]]. | + | With WinSCP you can easily upload and manage files on your Microsoft Azure Storage account container using the [[sftp|SFTP protocol]]. |
| ===== Before Starting ===== | ===== Before Starting ===== | ||
| - | Before starting you should [[guide_install|have WinSCP installed]]. | + | Before starting, you should [[guide_install|have WinSCP installed]]. |
| ===== Enabling SFTP access to the storage account ===== | ===== Enabling SFTP access to the storage account ===== | ||
| - | * SFTP access is supported by storage accounts with hierarchical namespaces enabled only (aka //Azure Data Lake Gen2// storage accounts). Existing flat //Blob service// accounts need to be upgraded. | + | * SFTP access is only supported by storage accounts with hierarchical namespaces enabled (aka //Azure Data Lake Gen2// storage accounts). Existing flat //Blob service// accounts need to be upgraded. |
| - | * To enable SFTP access to an existing hierarchical storage account, in storage account view, go to //Settings > SFTP// and click //Enable SFTP//. | + | * To enable SFTP access to an existing hierarchical storage account, in the storage account view, go to //Settings > SFTP// and click //Enable SFTP//. |
| - | * When creating new storage account, on //Advanced// page, check //Enable hierarchical namespace// and //Enable SFTP//. | + | * When creating a new storage account, on the //Advanced// page, check //Enable hierarchical namespace// and //Enable SFTP//. |
| //Enabling SFTP on Azure storage has an hourly billing impact.// | //Enabling SFTP on Azure storage has an hourly billing impact.// | ||
| - | ===== Connecting to the storage accounts ===== | + | ===== Connecting to the storage account ===== |
| - | To connect to a storage account with SFTP, start WinSCP. [[ui_login|Login dialog]] will appear. On the dialog: | + | To connect to a storage account with SFTP, start WinSCP. The [[ui_login|Login dialog]] will appear. In the dialog: |
| - | * Make sure //New site// node is selected. | + | * Make sure the //New site// node is selected. |
| - | * On the //New site// node, make sure //%%SFTP%%// protocol is selected. | + | * On the //New site// node, make sure the //%%SFTP%%// protocol is selected. |
| - | * Enter //Host name// in format ''storage-account-name.blob.core.windows.net''. | + | * Enter the //Hostname// in the format ''storage-account-name.blob.core.windows.net''. |
| + | * Next, configure authentication using one of the mechanisms shown below. | ||
| ===== Configuring container authentication ===== | ===== Configuring container authentication ===== | ||
| - | SFTP interface to Azure storage accounts supported two authentication mechanism – A legacy "local account" authentication and an Entra ID OpenSSH certificate authentication. | + | The SFTP interface for Azure storage accounts supports two authentication mechanisms – legacy "local account" authentication and Entra ID OpenSSH certificate authentication. |
| ==== Local account authentication ==== | ==== Local account authentication ==== | ||
| - | To add a new local account, in //Settings > SFTP// view, click //Add local user//, and | + | To add a new local account, in the //Settings > SFTP// view, click //Add local user//, and: |
| * specify the //Username//, | * specify the //Username//, | ||
| - | * select desired authentication method (password or key pair), | + | * select the desired authentication method (password or key pair), |
| - | * in //Permissions// tab, select //Container// to access with the local account, and specify its permissions. | + | * in the //Permissions// tab, select a //Container// to access with the local account, and specify its //Permissions//. |
| + | |||
| + | When specifying the //Username// in WinSCP, use the format ''storage-account-name.container-name.local-account-username''. Authenticating with the local user gives you access to the selected container only. | ||
| - | When specifying //User name// in WinSCP, use a format ''storage-account-name.container-name.local-account-username''. Authenticating with the local user gives you access to the selected container only. | ||
| ==== Entra ID OpenSSH certificate authentication ==== | ==== Entra ID OpenSSH certificate authentication ==== | ||
| - | As of May 2026, Entra ID OpenSSH certificate authentication is still a preview feature that you need to register for. In //Preview Features// view, search for //"SFTP Entra ID Support"// and click //Register//. | + | As of May 2026, Entra ID OpenSSH certificate authentication is still a preview feature that you need to register for. In the Azure //Preview Features// view, search for //"SFTP Entra ID Support"// and click //Register//. |
| - | To generate the certificate, in //Settings > SFTP// view, click //Generate SSH Certificate// and download both the generated certificate and the private key. Select both the private key and the certificate on the [[ui_login_authentication|//Authentication// page]] of Advanced Site Settings dialog. | + | To generate the certificate, in the //Settings > SFTP// view, click //"%%Generate SSH Certificate%%"// and download both the generated certificate and the private key. |
| - | with Azure CLI, make sure that you: | + | When configuring the authentication in WinSCP: |
| + | |||
| + | * When specifying the //Username//, use the format ''storage-account-name.username'', where ''username'' is the part of your Azure account username before the ''@'' sign. For example, if your Storage account name is ''winscpstorage'' and your Azure account username is ''martin@example.com'', then use ''winscpstorage.martin'' for the //Username// in WinSCP. | ||
| + | * Select both the generated private key and the certificate on the [[ui_login_authentication|//Authentication// page]] in the [[ui_login_advanced|advanced site settings]]. As the private key is generated in OpenSSH format, let WinSCP convert the key to PuTTY format. | ||
| - | * have Azure CLI installed, | + | Authenticating with a certificate gives you access to all containers that your Azure account has access to. The SFTP interface lists the containers in the root directory. Unfortunately, it does not list them as folders, so you won't be able to enter them directly with WinSCP. Instead, you can use the [[task_navigate#manual|//Open Directory// command]] and type the container name manually. Alternatively, if you disable the [[ui_login_directories|//Resolve symbolic links//]] session setting, WinSCP will allow you to enter containers by double-clicking them (even though they still won't look like subfolders in the root directory listing). |
| - | * are logged in (''az login'') and | + | |
| - | * have ''sftp'' extension installed (''az extension add --name sftp''). | + | The certificate is only valid for 65 minutes. For this reason, you will likely want to automate the generation. You can use any Azure API, for example, the Azure CLI [[https://learn.microsoft.com/en-us/cli/azure/sftp#az-sftp-cert|''az sftp cert'' command]]. To automate key conversion to PuTTY format, use WinSCP's [[commandline#keygen|''/keygen'' commandline]]. |
| - | Generate a certificate with: | ||
| <code batch> | <code batch> | ||
| - | az sftp cert --file .\my_cert.pub | + | call az sftp cert --file .\id_rsa-cert.pub --yes |
| + | winscp.com /keygen id_rsa /output=id_rsa.ppk /certificate=id_rsa-cert.pub | ||
| </code> | </code> | ||
| + | The ''id_rsa.ppk'' file generated by the above batch file contains both the certificate and the private key. So you only need to specify this one file as the private key file in the WinSCP session configuration. A separate certificate file is no longer needed. | ||
| ===== Further reading ===== | ===== Further reading ===== | ||
| - | * Guide to [[guide_upload|uploading files to SFTP/FTPS server]]; | + | * Guide to [[guide_upload|uploading files to an SFTP/FTPS server]]; |
| - | * Guide to [[guide_automation|automating operations]] (including upload). | + | * Guide to [[guide_automation|automating operations]] (including uploads). |