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

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:

   Expand table

   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.

   Important

   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.

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

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

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.

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.

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

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.

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.

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.

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
   

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