Differences
This shows you the differences between the selected revisions of the page.
| private_playground 2013-12-17 | private_playground 2026-06-02 (current) | ||
| Line 1: | Line 1: | ||
| ~~NOINDEX~~ | ~~NOINDEX~~ | ||
| + | ====== Connecting securely to Microsoft Azure Storage with SFTP ====== | ||
| + | With WinSCP you can easily upload and manage files on your Microsoft Azure Storage account container using the [[sftp|SFTP protocol]]. | ||
| - | ====== WinSCP 5.5 Changes ====== | + | ===== Before Starting ===== |
| - | WinSCP 5.5 is the major stable release of 2013. Users upgrading from [[history#5.1.8|WinSCP 5.1.8]] get the following improvements. | + | Before starting, you should [[guide_install|have WinSCP installed]]. |
| - | ===== Improved GUI Experience ====== | + | ===== Enabling SFTP access to the storage account ===== |
| - | * New toolbar icons and 16x16 icon. [[bug>290]] | + | * 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. |
| - | * Simplified [[ui_copy|Transfer options]] dialog: | + | * To enable SFTP access to an existing hierarchical storage account, in the storage account view, go to //Settings > SFTP// and click //Enable SFTP//. |
| - | * The dialog is shown only on the first transfer, when using drag&drop, unless user explicitly opts to show it the next time. | + | * When creating a new storage account, on the //Advanced// page, check //Enable hierarchical namespace// and //Enable SFTP//. |
| - | * Moved the //New and updated files only// option to Transfer settings. | + | |
| - | * Moved the //Do not show this dialog box again// checkbox below buttons. | + | |
| - | * Hiding //Transfer each file individually// when not applicable. | + | |
| - | * Icon to distinguish Copy/Move operation. | + | |
| - | * //Do not show this dialog box again// implies saving transfer settings | + | |
| - | * Improved working with [[transfer_settings|transfer settings]] and presets: | + | |
| - | * Not showing default Text mode file mask in //Transfer settings// box. | + | |
| - | ···* Showing even default Binary Transfer type in //Transfer settings// box. | + | |
| - | * Removed "Exclude temporaries" transfer settings preset. | + | |
| - | * Added "Newer and updates files only" transfer settings preset. | + | |
| - | * Reorganized //Transfer settings// drop down menu, including new //Presets// header. | + | |
| - | * Hiding unusable presets from //Transfer settings// drop down menu. | + | |
| - | * Merged configuration of default transfer settings and transfer settings presets. | + | |
| - | * Using "Download" and "Upload" commands to distinguish copying to local and remote directories respectively. | + | |
| - | * Using "Download and Delete" and "Upload and Delete" commands instead of "Move" to distinguish moving files to local and remote directories respectively. | + | |
| - | * Optionally keeping completed transfers in queue list for configurable period of time. [[bug>584]] | + | |
| - | * Replaced file operation toolbar, bottom hot key bar and upload/download toolbar with specialized local and remote file toolbars to allow manipulating local/remote files using mouse, without need to change panel focus (Commander interface only). | + | |
| - | * Improved incremental search for sites on Login dialog: [[bug>984]] | + | |
| - | * Text is searched anywhere in the site name, not only at the beginning. | + | |
| - | * Next/previous matching sites can be searched for. | + | |
| - | * Search text is shown below site list. | + | |
| - | * Displaying queue status on taskbar button. [[bug>151]] | + | |
| - | * Replaced Selection toolbar with specialized local and remote Selection toolbars (Commander interface only). | + | |
| - | * Added label to the most important toolbar buttons. They can be optionally hidden including already existing labels like Command-line label (Commander interface), Address label (Explorer interface) and New session tab label. | + | |
| - | * Moved //Commands// toolbar of Commander interface first. | + | |
| - | * Find files command moved from Commands toolbar to Remote Navigation toolbar and is now available regardless of focused panel. | + | |
| - | * Renamed //Add to Bookmarks// command to [[task_navigate#bookmarks|Add Path to Bookmarks]]. | + | |
| - | * Removed //Close// toolbar button from Editor and Log windows. | + | |
| - | * //Session// menu and toolbar reorganized. | + | |
| - | * Increased height of path labels (Commander interface only). | + | |
| - | * Single-file queue transfers occupy only single line in background transfer queue list. | + | |
| - | * Increased height of background transfer queue list row. | + | |
| - | * User interface icons are shown also in Setup. | + | |
| - | * Turned off automatic stretching of Transfer settings toolbar. | + | |
| - | * Column //Attr// is hidden by default on local panel. | + | |
| - | * Default (installation) width of the Commander interface is larger, if the screen resolution allows it. | + | |
| - | * Added //Download// and //Download and Delete// buttons on //Commands// toolbar of Explorer interface. | + | |
| - | * Moved //Panels// node on [[ui_preferences|Preferences]] dialog to the top-level to reduce nesting. | + | |
| - | * Horizontal line above file background transfer queue list splitter to highlight its presence. | + | |
| - | * Disabling whole //Once Empty// submenu, when queue is empty. | + | |
| - | * Using own context menu for local files (similar to existing context menu for remote files) by default. [[bug>163]] | + | |
| - | · * First column in Editor list in preferences is editor name. | + | |
| - | * Icons are no longer dimmed with Office XP theme. | + | |
| - | * Tab with disconnected session is greyed. | + | |
| - | * Removed //SSH Protocol version// from Site tooltip. | + | |
| - | * When file cannot be loaded using selected encoding in Internal editor, error is shown. On error loading default encoding, attempts to load using another encoding. [[bug>971]] | + | |
| - | * On main window views without focus respond to mouse wheel. [[bug>846]] | + | |
| - | * Export to INI file moved from Preferences to Login dialog. | + | |
| - | * In Commander interface, the keyboard shortcuts F3 and F5 can optionally have the same meaning as in Windows Explorer (//Find File// and //Refresh//). | + | |
| - | * Changing session port number on Login dialog to well know port, updates protocol automatically. | + | |
| - | * Additional ''F5'' shortcut to reload file in internal editor. [[bug>986]] | + | |
| - | * Calculating hot track color of path label to be in contrast with background. [[bug>992]] | + | |
| - | * Simplifying [[ui_overwrite|overwrite confirmation]] prompt: [[bug>993]] | + | |
| - | * Grouping advanced commands to drop down menu under button with related common command. | + | |
| - | * Added thousands separators to sizes. | + | |
| - | * File sizes on [[ui_synchronize_checklist|Synchronization Checklist]] and [[ui_find|Find]] dialogs are optionally shown using short format. Use //Show files sizes in short format// checkbox in the //[[ui_pref_panels|Panels]] page// on the Preferences dialog to control this feature. | + | |
| - | * Changing default tabulator size to 8. | + | |
| - | * Swapped order of //Use MLSD command for directory listing// and //Support for listing of hidden files// FTP session options. Also disabling the latter unless the first is set to //Off//. | + | |
| - | * Simplified [[ui_login|Login dialog]]: | + | |
| - | * Both site tree and basic session controls are visible at the same time. | + | |
| - | * Login dialog is resizable. [[bug>378]] | + | |
| - | * Modal editing of sites. | + | |
| - | * Advanced session controls moved to a separate dialog Advanced Site Settings dialog. | + | |
| - | * Context menu for site tree. | + | |
| - | * Site name and path are specified separately when saving site. | + | |
| - | * Separate entry for //New Site// in site tree. | + | |
| - | * Global settings such as //Interface// and //Logging// removed from Login dialog. | + | |
| - | * Language selection moved from //Languages// button of Login dialog to //Languages// page of Preferences dialog. | + | |
| - | * Display of sessions in workspace. | + | |
| - | * SSH //Private key file// box moved to //SSH tab// of Advanced Site Settings dialog. | + | |
| - | * Buttons that open drop down menu are marked with an arrow. | + | |
| - | * New icons for Console, Find and Synchronization Checklist windows. | + | |
| - | * Session settings can be exported also to KiTTY, when opening session in PuTTY/KiTTY. | + | |
| - | * Configurable registry key for exporting sessions to PuTTY(-like) clients. [[bug>1006]] | + | |
| - | * New shell icons for site, site folder and workspace. | + | |
| - | * Relevant help is available for more error messages. | + | |
| - | * Renamed Login and Preferences dialogs' "tabs" to "pages". | + | |
| - | * Prompt answers //Yes to All/No to All// moved closer to the primary //Yes/No// answers. | + | |
| - | * Internal error message boxes feature //Report// button to directly report the error on support forum. | + | |
| - | * Allowing filtering subdirectories. [[bug>1018]] | + | |
| - | * Convenience and robustness improvements for working with master password: [[bug>1023]] | + | |
| - | * Avoiding repetitive master password prompts, when editing site. | + | |
| - | * Detect and warn when trying to set/clear master password while another instance of WinSCP is running. | + | |
| - | * Not prompting for master password for read-only site view. | + | |
| - | * Hiding an actual password length from read-only site view. | + | |
| - | * When setting/changing/clearing master password, collecting errors while recrypting passwords individually, not to abort whole process on a single error. | + | |
| - | * Gracefully handling stray encrypted passwords, when master password is actually not enabled or different. | + | |
| - | * Feedback and repeated prompt on incorrectly entered master password in scripting mode. | + | |
| - | * Showing number of active and pending transfers on queue label. [[bug>1031]] | + | |
| - | * Information about TLS/SSL version and cipher used in available on Server and protocol information dialog and main window status bar. | + | |
| - | * ''Ctrl+W'' shortcut for closing tab (session). [[bug>1035]] | + | |
| - | ===== Improved Working with Sites and Workspaces ===== | + | //Enabling SFTP on Azure storage has an hourly billing impact.// |
| - | ··* Using term //Site// instead of //Stored session//. | + | ===== Connecting to the storage account ===== |
| - | * //Site Manager// command. [[bug>855]] | + | |
| - | * [[ui_import|Sites import]] from Filezilla. [[bug>61]] | + | |
| - | * [[workspace|Workspace]] can be saved. [[bug>776]] | + | |
| - | * Whole site folder can be opened at once. [[bug>424]] | + | |
| - | * Desktop shortcut to open site folder can be created. | + | |
| - | == Improved "During and After Installation" Experience == | + | To connect to a storage account with SFTP, start WinSCP. The [[ui_login|Login dialog]] will appear. In the dialog: |
| - | * Only shortcut to WinSCP itself is created in Start menu. [[bug>616]] | + | * Make sure the //New site// node is selected. |
| - | ··* When upgrading, setup offers to restart Windows Explorer (or other applications), when drag&drop shell extension needs to be updated. [[bug>686]] | + | * On the //New site// node, make sure the //%%SFTP%%// protocol is selected. |
| - | ··* While installing, setup offers sites import from PuTTY or Filezilla. | + | * Enter the //Hostname// in the format ''storage-account-name.blob.core.windows.net''. |
| - | ··* On first edit, WinSCP offers configuration of user's custom text editor as default editor. | + | * Next, configure authentication using one of the mechanisms shown below. |
| - | * Command to Import/restore configuration from INI file. | + | |
| - | ===== Improved Scripting and .NET ===== | + | ===== Configuring container authentication ===== |
| - | * Transfer resume support can be controlled in scripting (''-resumesupport'' switch of file transfer commands) and .NET assembly (''TransferOptions.ResumeSupport'' property). [[bug>834]] | + | The SFTP interface for Azure storage accounts supports two authentication mechanisms – legacy "local account" authentication and Entra ID OpenSSH certificate authentication. |
| - | * Transfer progress feedback using ''Session.FileTransferProgress'' event. [[bug>818]] | + | |
| - | * For special cases, it is possible to accept any SSH host key or any TLS/SSL certificate (with warning) using ''-hostkey=*'' in scripting and ''SessionOptions.GiveUpSecurityAndAcceptAnySshHostKey'' or ''SessionOptions.GiveUpSecurityAndAcceptAnySshHostKey'' in .NET assembly. [[bug>815]] | + | |
| - | * Before opening session using command-line parameter in scripting, warning is printed, that this is deprecated function. | + | |
| - | * Retrospectively logging previous script records when session is starting. | + | |
| - | * Printing transfer progress for small files in bytes in scripting. [[bug>964]] | + | |
| - | * Renamed WinSCP .NET assembly to ''winscpnet.dll'' to avoid conflicts with ''winscp.exe''. [[bug>945]] | + | |
| - | * Command //Clear caches// clears also cache of separate shell session. | + | |
| - | * Change: Not trying to kill WinSCP process from .NET assembly ''Session'' finalizer. | + | |
| - | * Event ''Session.FileTransferProgress'' is always raised when file transfer completes. | + | |
| - | * Custom command pattern ''!`command`'' that expands to output of local command. | + | |
| - | * Subset of custom command patterns can be used in PuTTY path, including ''!/'', ''!@'', ''!U'', ''!P'', ''!?prompt?!'' and ''!`command`''. This among other allows opening PuTTY in the same directory as current WinSCP working directory [[bug>326]]; or using different SSH client, such as KiTTY [[bug>966]]. | + | |
| - | * Synchronization preview in scripting. [[bug>885]] | + | |
| - | ===== Other Improvements ===== | ||
| - | ··* Change: Session from commandline and/or from jump list is opened by default using existing WinSCP instance. [[bug>769]] | + | ==== Local account authentication ==== |
| - | * Writing INI file to user's profile, if program path is not writable. [[bug>817]] | + | |
| - | * Any mouse or keyboard input cancels or resets reconnect countdown. | + | |
| - | * Increased default reconnect interval for idle sessions to 9 seconds. | + | |
| - | * Reconnect interval for idle sessions can be configured independently. | + | |
| - | * Reporting an error when reading of local directory fails during operation. [[bug>952]] | + | |
| - | * When SFTP connection is rejected, knock FTP port. If open suggest using FTP protocol. | + | |
| - | * Dropped support for Windows 2000. Minimal supported version is Windows XP. | + | |
| - | * Using GiB scale for large file sizes. [[bug>913]] | + | |
| - | * Option to reconnect disconnected non-active session, when saving file opened from that session. [[bug>917]] | + | |
| - | * Use of ''MLSD'' FTP command is configurable. [[bug>927]] | + | |
| - | * Allowing host key import for SSH protocols only. | + | |
| - | * Added larger values to initial offer of speed limits. [[bug>987]] | + | |
| - | * Offering to remember password for duration of session on [[ui_authenticate#password|password prompt]] (when settings //Remember password for duration of session// is turned off). [[bug>610]] | + | |
| - | * Not allowing //Timezone offset// session setting with FTP protocol, while ''MLSD'' listing command is used. | + | |
| - | * Not opening session from jumplist in existing instance, if it is showing error. | + | |
| - | * Moved option to remember session password from //Background// to //[[ui_pref_security|Security]] page// of Preferences dialog. | + | |
| - | * Cached SSH host keys are imported by default. | + | |
| - | * Not showing disconnect error message before reconnecting inactive session to upload edited file. | + | |
| - | * Performance improvement. | + | |
| - | * Configurable minimal and maximal supported TLS/SSL version. | + | |
| - | ===== Bug Fixes ===== | + | To add a new local account, in the //Settings > SFTP// view, click //Add local user//, and: |
| - | * Bug fix: Scripting command ''synchronize'' sometimes did not announce that there is nothing to synchronize. | + | * specify the //Username//, |
| - | * Bug fix: First Authenticate log entry was trimmed temporarily. | + | * select the desired authentication method (password or key pair), |
| - | * Bug fix: Separators on toolbars were showing "E" hint. | + | * in the //Permissions// tab, select a //Container// to access with the local account, and specify its //Permissions//. |
| - | * Bug fix: Incorrect file icon overlay positioning. | + | |
| - | * Bug fix: Not drawing own shortcut overlay over shortcut icons. | + | |
| - | * Bug fix: Records on Authentication window were temporarily truncated. | + | |
| - | * Bug fix: Selection on file panel was not visually updated when panel received/lost focus. | + | |
| - | * Bug fix: Panel path label was not deactivated when focus moved from directory tree to file transfer queue. | + | |
| - | * Bug fix: //Download// command was not highlighted as default in remote directory context menu when //Operation to perform on double-click// was set to //Copy//. | + | |
| - | * Bug fix: Text mode transfers should not be resumed FTP protocol. [[bug>965]] | + | |
| - | * Bug fix: No error is shown in Internal editor, when file cannot be loaded using selected encoding. [[bug>971]] | + | |
| - | * Bug fix: It was not possible to pass sequence of consecutive delimiters when skipping to the next "word" in path input boxes. | + | |
| - | * Bug fix: Opened/Closed folder icons on Location profile dialog were swapped. | + | |
| - | * Bug fix: Wrong background of path labels with disabled themes. [[bug>990]] | + | |
| - | * Bug fix: Cannot import FileZilla sites in folders. [[bug>994]] | + | |
| - | * Bug fix: FileZilla site logon type is not imported. [[bug>995]] | + | |
| - | * Bug fix: Installer was asking for name of program menu folder, although no folder is created anymore. | + | |
| - | * Bug fix: Failure when using mouse wheel with mouse cursor outside of WinSCP window. [[bug>998]] | + | |
| - | * Bug fix: Opening session in PuTTY does not work. [[bug>1002]] | + | |
| - | * Bug fix: Failure when disposing ''Session'' of .NET assembly. [[bug>1008]] | + | |
| - | * Bug fix: Constant CPU usage when queue is empty. [[bug>1013]] | + | |
| - | * Bug fix: Missing labels for some answers in scripting (such as //Yes to All/////No to All// on overwrite confirmation prompt). | + | |
| - | * Bug fix: Option //Support for listing if hidden files// is not working. [[bug>1015]] | + | |
| - | * Bug fix: Mismatched warnings about accepting any SSH host key and TLS/SSL certificate respectively. | + | |
| - | * Bug fix: Local directory box was missing on Advanced Site Settings dialog. | + | |
| - | * Bug fix: Incorrect encryption of passwords protected with master password, potentially leading to loss of stored passwords. [[bug>1022]] | + | |
| - | * Bug fix: When adding password to existing site, new password can possibly be unprotected with master password. | + | |
| - | ··* Bug fix: Pending queued transfers were omitted from queue status display on taskbar button. [[bug>1030]] | + | |
| - | * Bug fix: Failure when using context menu of disconnected session tab. [[bug>1033]] | + | |
| - | * Bug fix: Failure when right-clicking empty area on site tree. [[bug>1036]] | + | |
| - | ===== RAW ===== | + | 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. |
| + | |||
| + | |||
| + | ==== 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 the Azure //Preview Features// view, search for //"SFTP Entra ID Support"// and click //Register//. | ||
| + | |||
| + | 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 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. | ||
| + | |||
| + | 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 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> | ||
| + | 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> | ||
| + | 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 ===== | ||
| + | * Guide to [[guide_upload|uploading files to an SFTP/FTPS server]]; | ||
| + | * Guide to [[guide_automation|automating operations]] (including uploads). | ||