Configure IoT Hub file uploads using the Azure portal

Prerequisites

• An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.

• An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in Create an IoT hub.

Configure your IoT hub in the Azure portal

1. In the Azure portal, navigate to your IoT hub and select File upload to display the file upload properties. Then select Azure Storage Container under Storage container settings.

   

2. Select an Azure Storage account and blob container in your current subscription to associate with your IoT hub. If necessary, you can create an Azure Storage account on the Storage accounts pane and create a blob container on the Containers pane.

   

3. After you've selected an Azure Storage account and blob container, configure the rest of the file upload properties.

   • Receive notifications for uploaded files: Enable or disable file upload notifications via the toggle.

   • SAS TTL: This setting is the time-to-live of the SAS URIs returned to the device by IoT Hub. Set to one hour by default but can be customized to other values using the slider.

   • File notification settings default TTL: The time-to-live of a file upload notification before it's expired. Set to one day by default but can be customized to other values using the slider.

   • File notification maximum delivery count: The number of times the IoT Hub attempts to deliver a file upload notification. Set to 10 by default but can be customized to other values using the slider.

   • Authentication type: By default, Azure IoT Hub uses key-based authentication to connect and authorize with Azure Storage. You can also configure user-assigned or system-assigned managed identities to authenticate Azure IoT Hub with Azure Storage. Managed identities provide Azure services with an automatically managed identity in Microsoft Entra ID in a secure manner. To learn how to configure managed identities, see IoT Hub support for managed identities. After you've configured one or more managed identities on your Azure Storage account and IoT hub, you can select one for authentication with Azure storage with the System-assigned or User-assigned buttons.

     Note

     The authentication type setting configures how your IoT hub authenticates with your Azure Storage account. Devices always authenticate with Azure Storage using the SAS URI that they get from the IoT hub.

4. Select Save to save your settings. Be sure to check the confirmation for successful completion. Some selections, like Authentication type, are validated only after you save your settings.

Prerequisites

• An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.

• An IoT hub in your Azure subscription. If you don't have a hub yet, you can follow the steps in Create an IoT hub.

• An Azure Storage account with a blob container. If you don't have an Azure Storage account, you can use the Azure CLI to create one. For more information, see Create a storage account.

• Use the Bash environment in Azure Cloud Shell. For more information, see Get started with Azure Cloud Shell.

  

• If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

  • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Authenticate to Azure using Azure CLI.

  • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage extensions with the Azure CLI.

  • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Sign in and set your Azure account

Sign in to your Azure account and select your subscription. If you're using Azure Cloud Shell, you should be signed in already; however, you still might need to select your Azure subscription if you have multiple subscriptions.

1. At the command prompt, run the login command:

   az login
   

   Follow the instructions to authenticate using the code and sign in to your Azure account through a web browser.

2. If you have multiple Azure subscriptions, signing in to Azure grants you access to all the Azure accounts associated with your credentials. Use the following command to list the Azure accounts available for you to use:

   az account list
   

   Use the following command to select the subscription that you want to use to run the commands to create your IoT hub. You can use either the subscription name or ID from the output of the previous command:

   az account set --subscription {your subscription name or id}
   

Configure storage account access

The following steps assume that you created your storage account using the Resource Manager deployment model, and not the Classic deployment model.

To configure file uploads from your devices, you need to give your IoT hub access permissions to the Azure Storage account. The storage account must be in the same subscription as your IoT hub. You also need the name of a blob container in the storage account.

You can use either key-based or identity-based authentication to provide access permissions. Microsoft recommends identity-based authentication as a more secure option.

Key-based authentication

For key-based authentication, provide the connection string for your storage account. Use the az storage account show-connection-string command to retrieve your storage account keys.

Make a note of the connectionString value. The connection string looks similar to the following output:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

Identity-based authentication

You can use system-assigned managed identities or user-assigned managed identities for identity-based authentication. For more information, see IoT Hub support for managed identities.

Use the az role assignment create command to assign a role to your managed identity. For more information, see Assign an Azure role for access to blob data.

Configure your IoT hub

You can now configure your IoT hub to enable the ability to upload files to the IoT hub using your storage account details.

The configuration requires the following values:

• Storage container: A blob container in an Azure storage account in your current Azure subscription to associate with your IoT hub. You retrieved the necessary storage account information in the preceding section. IoT Hub automatically generates SAS URIs with write permissions to this blob container for devices to use when they upload files.

• Receive notifications for uploaded files: Enable or disable file upload notifications.

• SAS TTL: This setting is the time-to-live of the SAS URIs returned to the device by IoT Hub. Set to one hour by default.

• File notification settings default TTL: The time-to-live of a file upload notification before it expires. Set to one day by default.

• File notification maximum delivery count: The number of times the IoT Hub attempts to deliver a file upload notification. Set to 10 by default.

• File notification lock duration: The lock duration for the file notification queue. Set to 60 seconds by default.

• Authentication type: The type of authentication for IoT Hub to use with Azure Storage. This setting determines how your IoT hub authenticates and authorizes with Azure Storage. The default is key-based authentication; however, the system-assigned or user-assigned managed identity authentication options are recommended. Managed identities provide Azure services with an automatically managed identity in Microsoft Entra ID in a secure manner.

  Note

  The authentication type setting configures how your IoT hub authenticates with your Azure Storage account. Devices always authenticate with Azure Storage using the SAS URI that they get from the IoT hub.

The following commands show how to configure the file upload settings on your IoT hub. These commands are shown separately for clarity, but, typically, you would issue a single command with all the required parameters for your scenario. Include quotes where they appear in the command line. Don't include the braces. More detail about each parameter can be found in the Azure CLI documentation for the az iot hub update command.

The following command configures the storage account and blob container.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}" 

The following command sets the SAS URI time to live to the default (one hour).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1 

The following command enables file notifications and sets the file notification properties to their default values. (The file upload notification time to live is set to one hour and the lock duration is set to 60 seconds.)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

The following command configures key-based authentication:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

The following command configures authentication using the IoT hub's system-assigned managed identity. Before you can run this command, you need to enable the system-assigned managed identity for your IoT hub and grant it the correct role-based access control role on your Azure Storage account. To learn how, see IoT Hub support for managed identities.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system] 

The following commands retrieve the user-assigned managed identities configured on your IoT hub and configure authentication with one of them. Before you can use a user-assigned managed identity to authenticate, it must be configured on your IoT hub and granted an appropriate role-based access control role on your Azure Storage account. For more detail and steps, see IoT Hub support for managed identities.

To query for user-assigned managed identities on your IoT hub, use the az iot hub identity show command.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

The command returns a collection of the user-assigned managed identities configured on your IoT hub. The following output shows a collection that contains a single user-assigned managed identity.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

The following command configures authentication to use the user-assigned identity above.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

You can review the settings on your IoT hub using the following command:

az iot hub show --name {your iot hub name}

To review only the file upload settings, use the following command:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

For most situations, using the named parameters in the Azure CLI commands is easiest; however, you can also configure file upload settings with the --set parameter. The following commands can help you understand how.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

Prerequisites

• An active Azure account. If you don't have an account, you can create a free account in just a couple of minutes.

• An Azure IoT hub. If you don't have an IoT hub, you can use the New-AzIoTHub cmdlet to create one or follow the steps in Create an IoT hub.

• An Azure storage account. If you don't have an Azure storage account, you can use the Azure Storage PowerShell cmdlets to create one or use the portal to Create a storage account.

• Use the PowerShell environment in Azure Cloud Shell.

  

• If you prefer, install PowerShell locally.

  • Install the Azure Az PowerShell module. (The module is installed by default in the Azure Cloud Shell PowerShell environment.)
  • Sign in to PowerShell by using the Connect-AzAccount command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with Azure PowerShell.

Sign in and set your Azure account

Sign in to your Azure account and select your subscription. If you're using Azure Cloud Shell, you should be signed in already; however, you still might need to select your Azure subscription if you have multiple subscriptions.

1. At the PowerShell prompt, run the Connect-AzAccount cmdlet:

   Connect-AzAccount
   

2. If you have multiple Azure subscriptions, signing in to Azure grants you access to all the Azure subscriptions associated with your credentials. Use the Get-AzSubscription command to list the Azure subscriptions available for you to use:

   Get-AzSubscription
   

   Use the following command to select the subscription that you want to use to run the commands to manage your IoT hub. You can use either the subscription name or ID from the output of the previous command:

   Select-AzSubscription `
       -Name "{your subscription name}"
   

   Note

   The Select-AzSubscription command is an alias of the Select-AzContext that allows you to use the subscription name (Name) or subscription ID (Id) returned by the Get-AzSubscription command rather than the more complex context name required for the Select-AzContext command.

Retrieve your storage account details

The following steps assume that you created your storage account using the Resource Manager deployment model, and not the Classic deployment model.

To configure file uploads from your devices, you need the connection string for an Azure storage account. The storage account must be in the same subscription as your IoT hub. You also need the name of a blob container in the storage account. Use the Get-AzStorageAccountKey command to retrieve your storage account keys:

Get-AzStorageAccountKey `
  -Name {your storage account name} `
  -ResourceGroupName {your storage account resource group}

Make a note of the key1 storage account key value. You need it in the following steps.

You can either use an existing blob container for your file uploads or create new one:

• To list the existing blob containers in your storage account, use the New-AzStorageContext and Get-AzStorageContainer commands:

  $ctx = New-AzStorageContext `
      -StorageAccountName {your storage account name} `
      -StorageAccountKey {your storage account key}
  Get-AzStorageContainer -Context $ctx
  

• To create a blob container in your storage account, use the New-AzStorageContext and New-AzStorageContainer commands:

  $ctx = New-AzStorageContext `
      -StorageAccountName {your storage account name} `
      -StorageAccountKey {your storage account key}
  New-AzStorageContainer `
      -Name {your new container name} `
      -Permission Off `
      -Context $ctx
  

Configure your IoT hub

You can now configure your IoT hub to upload files to the IoT hub using your storage account details.

The configuration requires the following values:

• Storage container: A blob container in an Azure storage account in your current Azure subscription to associate with your IoT hub. You retrieved the necessary storage account information in the preceding section. IoT Hub automatically generates SAS URIs with write permissions to this blob container for devices to use when they upload files.

• Receive notifications for uploaded files: Enable or disable file upload notifications.

• SAS TTL: This setting is the time-to-live of the SAS URIs returned to the device by IoT Hub. Set to one hour by default.

• File notification settings default TTL: The time-to-live of a file upload notification before it's expired. Set to one day by default.

• File notification maximum delivery count: The number of times the IoT Hub attempts to deliver a file upload notification. Set to 10 by default.

Use the Set-AzIotHub command to configure the file upload settings on your IoT hub:

Set-AzIotHub `
    -ResourceGroupName "{your iot hub resource group}" `
    -Name "{your iot hub name}" `
    -FileUploadNotificationTtl "01:00:00" `
    -FileUploadSasUriTtl "01:00:00" `
    -EnableFileUploadNotifications $true `
    -FileUploadStorageConnectionString "DefaultEndpointsProtocol=https;AccountName={your storage account name};AccountKey={your storage account key};EndpointSuffix=core.windows.net" `
    -FileUploadContainerName "{your blob container name}" `
    -FileUploadNotificationMaxDeliveryCount 10