Differences
This shows you the differences between the selected revisions of the page.
| 2026-05-21 | 2026-05-21 | ||
| no summary (martin) | no summary (martin) | ||
| 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 container 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 //Host name// in the format ''storage-account-name.blob.core.windows.net''. |
| - | * Further, configure authentication using one of the mechanisms shown below. | + | * Next, configure authentication using one of the mechanisms shown below. |
| ===== Configuring container authentication ===== | ===== Configuring container authentication ===== | ||
| - | SFTP interface to Azure storage accounts supports 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 a //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 //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. | + | When specifying the //User name// 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. |
| ==== 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 Azure //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. | + | To generate the certificate, in the //Settings > SFTP// view, click //"%%Generate SSH Certificate%%"// and download both the generated certificate and the private key. |
| When configuring the authentication in WinSCP: | When configuring the authentication in WinSCP: | ||
| - | * When specifying //User name//, use a 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 user name is ''martin@example.com'', then use ''winscpstorage.martin'' for //User name// in WinSCP. | + | * When specifying the //User name//, 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 user name is ''martin@example.com'', then use ''winscpstorage.martin'' for the //User name// in WinSCP. |
| - | * Select both the generated private key and the certificate on the [[ui_login_authentication|//Authentication// page]] in [[ui_login_advanced|advanced site settings]]. As the private key is generated in OpenSSH format, let WinSCP convert the key to PuTTY format. | + | * 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. |
| - | Authenticating with certificate gives you access to all containers to which 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 [[task_navigate#manual|//Open Directory// command]] and type the container name manually. Alternatively, if you disable [[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). | + | 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). |
| - | The certificate is valid for 65 minutes only. 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 [[commandline#keygen|''/keygen'' commandline]]. | + | 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]]. |
| <code batch> | <code batch> | ||
| Line 59: | Line 59: | ||
| winscp.com /keygen id_rsa /output=id_rsa.ppk /certificate=id_rsa-cert.pub | 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 WinSCP session configuration. A separate certificate file is no longer needed. | + | 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). |