Authorize access to Azure Blob Storage for an SSH File Transfer Protocol (SFTP) client

This article shows you how to authorize access to SFTP clients so that you can securely connect to the Blob Storage endpoint of your Azure Storage account by using an SFTP client.

To learn more about SFTP support for Azure Blob Storage, see SSH File Transfer Protocol (SFTP) in Azure Blob Storage.

Prerequisites

• Enable SFTP support for Azure Blob Storage. See Enable or disable SFTP support.

Create a local user

Azure Storage doesn't support shared access signature (SAS), or Microsoft Entra authentication for accessing the SFTP endpoint. Instead, you must use an identity called local user that can be secured with an Azure generated password or a secure shell (SSH) key pair. To grant access to a connecting client, the storage account must have an identity associated with the password or key pair. That identity is called a local user.

In this section, you'll learn how to create a local user, choose an authentication method, and assign permissions for that local user.

To learn more about the SFTP permissions model, see SFTP Permissions model.

Tip

This section shows you how to configure local users for an existing storage account. To view an Azure Resource Manager template that configures a local user as part of creating an account, see Create an Azure Storage Account and Blob Container accessible using SFTP protocol on Azure.

Choose an authentication method

You can authenticate local users connecting from SFTP clients by using a password or a Secure Shell (SSH) public-private key pair.

Important

While you can enable both forms of authentication, SFTP clients can connect by using only one of them. Multifactor authentication, whereby both a valid password and a valid public and private key pair are required for successful authentication is not supported.

Portal

1. In the Azure portal, navigate to your storage account.

2. Under Settings, select SFTP, and then select Add local user.

   

3. In the Add local user configuration pane, add the name of a user, and then select which methods of authentication you'd like associate with this local user. You can associate a password and / or an SSH key.

   If you select SSH Password, then your password appears when complete all of the steps in the Add local user configuration pane. SSH passwords are generated by Azure and are minimum 32 characters in length.

   If you select SSH Key pair, then select Public key source to specify a key source.

   

   The following table describes each key source option:

   Option	Guidance
   Generate a new key pair	Use this option to create a new public / private key pair. The public key is stored in Azure with the key name that you provide. The private key can be downloaded after the local user has been successfully added.
   Use existing key stored in Azure	Use this option if you want to use a public key that is already stored in Azure. To find existing keys in Azure, see List keys. When SFTP clients connect to Azure Blob Storage, those clients need to provide the private key associated with this public key.
   Use existing public key	Use this option if you want to upload a public key that is stored outside of Azure. If you don't have a public key, but would like to generate one outside of Azure, see Generate keys with ssh-keygen.

4. Select Next to open the Permissions tab of the configuration pane.

PowerShell

This section shows you how to authenticate by using either an SSH key or a password.

Authenticate by using an SSH key (PowerShell)

1. Choose the type of public key that you want to use.

   • Use existing key stored in Azure

     Use this option if you want to use a public key that is already stored in Azure. To find existing keys in Azure, see List keys. When SFTP clients connect to Azure Blob Storage, those clients need to provide the private key associated with this public key.

   • Use existing public key that is stored outside of Azure.

     If you don't yet have a public key, then see Generate keys with ssh-keygen for guidance about how to create one. Only OpenSSH formatted public keys are supported. The key that you provide must use this format: <key type> <key data>. For example, RSA keys would look similar to this: ssh-rsa AAAAB3N.... If your key is in another format, then a tool such as ssh-keygen can be used to convert it to OpenSSH format.

2. Create a public key object by using the New-AzStorageLocalUserSshPublicKey command. Set the -Key parameter to a string that contains the key type and public key. In the following example, the key type is ssh-rsa and the key is ssh-rsa a2V5....

   $sshkey = "ssh-rsa a2V5..."
   $sshkey = New-AzStorageLocalUserSshPublicKey -Key $sshkey -Description "description for ssh public key"
   

3. Create a local user by using the Set-AzStorageLocalUser command. If you're using an SSH key, then set the SshAuthorizedKey parameter to the public key object that you created in the previous step.

   The following example creates a local user and then prints the key to the console.

   $UserName = "mylocalusername"
   $localuser = Set-AzStorageLocalUser -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName -UserName $UserName -SshAuthorizedKey $sshkey -HasSharedKey $true -HasSshKey $true
   
   $localuser
   $localuser.SshAuthorizedKeys | ft
   

   Note

   Local users also have a sharedKey property that is used for SMB authentication only.

Authenticate by using a password (PowerShell)

1. Create a local user by using the Set-AzStorageLocalUser command, and set the -HasSshPassword parameter to $true.

   The following example creates a local user that uses password authentication.

   $UserName = "mylocalusername"
   $localuser = Set-AzStorageLocalUser -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName -UserName $UserName -HasSshPassword $true
   

2. You can create a password by using the New-AzStorageLocalUserSshPassword command. Set the -UserName parameter to the user name.

   The following example generates a password for the user.

   $password = New-AzStorageLocalUserSshPassword -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName -UserName $UserName
   $password 
   

   Important

   You can't retrieve this password later, so make sure to copy the password, and then store it in a place where you can find it. If you lose this password, you'll have to generate a new one. Note that SSH passwords are generated by Azure and are minimum 32 characters in length.

Azure CLI

This section shows you how to authenticate by using either an SSH key or a password.

Authenticate by using an SSH key (Azure CLI)

1. Choose the type of public key that you want to use.

   • Use existing key stored in Azure

     Use this option if you want to use a public key that is already stored in Azure. To find existing keys in Azure, see List keys. When SFTP clients connect to Azure Blob Storage, those clients need to provide the private key associated with this public key.

   • Use existing public key that is stored outside of Azure.

     If you don't yet have a public key, then see Generate keys with ssh-keygen for guidance about how to create one. Only OpenSSH formatted public keys are supported. The key that you provide must use this format: <key type> <key data>. For example, RSA keys would look similar to this: ssh-rsa AAAAB3N.... If your key is in another format, then a tool such as ssh-keygen can be used to convert it to OpenSSH format.

2. To create a local user that is authenticated by using an SSH key, use the az storage account local-user create command, and then set the --has-ssh-key parameter to a string that contains the key type and public key.

   The following example creates a local user named contosouser, and uses an ssh-rsa key with a key value of ssh-rsa a2V5... for authentication.

   az storage account local-user create --account-name contosoaccount -g contoso-resource-group -n contosouser --ssh-authorized-key key="ssh-rsa a2V5..." --has-ssh-key true --has-ssh-password true
   

   Note

   Local users also have a sharedKey property that is used for SMB authentication only.

Authenticate by using a password (Azure CLI)

1. To create a local user that is authenticated by using a password, use the az storage account local-user create command, and then set the --has-ssh-password parameter to true.

   The following example creates a local user named contosouser, and sets the --has-ssh-password parameter to true.

   az storage account local-user create --account-name contosoaccount -g contoso-resource-group -n contosouser --has-ssh-password true
   

2. Create a password by using the az storage account local-user regenerate-password command. Set the -n parameter to the local user name.

   The following example generates a password for the user.

   az storage account local-user regenerate-password --account-name contosoaccount -g contoso-resource-group -n contosouser  
   

   Important

   You can't retrieve this password later, so make sure to copy the password, and then store it in a place where you can find it. If you lose this password, you'll have to generate a new one. Note that SSH passwords are generated by Azure and are minimum 32 characters in length.

Give permission to containers

Choose which containers you want to grant access to and what level of access you want to provide. Those permissions apply to all directories and subdirectories in the container. To learn more about each container permission, see Container permissions.

If you want to authorize access at the file and directory level, you can enable ACL authorization. This capability is in preview and can be enabled only by using the Azure portal.

Portal

1. In the Permissions tab, select the containers that you want to make available to this local user. Then, select which types of operations you want to enable this local user to perform.

   

   Important

   The local user must have at least one container permission or ACL permission to the home directory of that container. Otherwise a connection attempt to that container will fail.

2. If you want to authorize access by using the access control lists (ACLs) associated with files and directories in this container, then select the Allow ACL authorization checkbox. To learn more about using ACLS to authorize SFTP clients, see ACLs.

   You can also add this local user to a group by assigning that user to a group ID. That ID can be any number or number scheme that you want. Grouping users allow you to add and remove users without the need to reapply ACLs to an entire directory structure. Instead, you can just add or remove users from the group.

   

   Note

   A user ID for the local user is automatically generated. You can't modify this ID, but you can see the ID after you create the local user by reopening that user in the Edit local user pane.

3. In the Home directory edit box, type the name of the container or the directory path (including the container name) that will be the default location associated with this local user (For example: mycontainer/mydirectory).

   To learn more about the home directory, see Home directory.

4. Select the Add button to add the local user.

   If you enabled password authentication, then the Azure generated password appears in a dialog box after the local user has been added.

   Important

   You can't retrieve this password later, so make sure to copy the password, and then store it in a place where you can find it.

   If you chose to generate a new key pair, then you'll be prompted to download the private key of that key pair after the local user has been added.

   Note

   Local users have a sharedKey property that is used for SMB authentication only.

PowerShell

1. Decide which containers you want to make available to the local user and the types of operations that you want to enable this local user to perform. Create a permission scope object by using the New-AzStorageLocalUserPermissionScope command, and setting the -Permission parameter of that command to one or more letters that correspond to access permission levels. Possible values are Read(r), Write (w), Delete (d), List (l), Create (c), Modify Ownership(o), Modify Permissions(p).

   The following example set creates a permission scope object that gives read and write permission to the mycontainer container.

   $permissionScope = New-AzStorageLocalUserPermissionScope -Permission rw -Service blob -ResourceName mycontainer 
   

   Important

   The local user must have at least one container permission for the container it is connecting to otherwise the connection attempt will fail.

2. Update the local user by using the Set-AzStorageLocalUser command. Set the -PermissionScope parameter to the permission scope object that you created earlier.

   The following example updates a local user with container permissions and then prints the permission scopes to the console.

   $UserName = "mylocalusername"
   $localuser = Set-AzStorageLocalUser -ResourceGroupName $resourceGroupName -StorageAccountName $storageAccountName -UserName $UserName -HomeDirectory "mycontainer" -PermissionScope $permissionScope
   
   $localuser
   $localuser.PermissionScopes | ft
   

Azure CLI

To update a local user with permission to a container, use the az storage account local-user update command, and then set the permission-scope parameter of that command to one or more letters that correspond to access permission levels. Possible values are Read(r), Write (w), Delete (d), List (l), Create (c), Modify Ownership(o), Modify Permissions(p).

The following example gives a local user name contosouser read and write access to a container named contosocontainer.

az storage account local-user update --account-name contosoaccount -g contoso-resource-group -n contosouser --home-directory contosocontainer --permission-scope permissions=rw service=blob resource-name=contosocontainer

Next steps

• Connect to Azure Blob Storage by using an SFTP client. See Connect from an SFTP client.

Related content

• SSH File Transfer Protocol (SFTP) support for Azure Blob Storage
• Enable or disable SSH File Transfer Protocol (SFTP) support in Azure Blob Storage
• Authorize access to Azure Blob Storage from an SSH File Transfer Protocol (SFTP) client
• Limitations and known issues with SSH File Transfer Protocol (SFTP) support for Azure Blob Storage
• Host keys for SSH File Transfer Protocol (SFTP) support for Azure Blob Storage
• SSH File Transfer Protocol (SFTP) performance considerations in Azure Blob storage