az iot hub device-identity
Note
This reference is part of the azure-iot extension for the Azure CLI (version 2.46.0 or higher). The extension will automatically install the first time you run an az iot hub device-identity command. Learn more about extensions.
Manage IoT devices.
Commands
Name | Description | Type | Status |
---|---|---|---|
az iot hub device-identity children |
Manage children device relationships for IoT edge devices. |
Extension | GA |
az iot hub device-identity children add |
Add devices as children to a target edge device. |
Extension | GA |
az iot hub device-identity children list |
Outputs the collection of assigned child devices. |
Extension | GA |
az iot hub device-identity children remove |
Remove child devices from a target edge device. |
Extension | GA |
az iot hub device-identity connection-string |
Manage IoT device's connection string. |
Extension | GA |
az iot hub device-identity connection-string show |
Show a given IoT Hub device connection string. |
Extension | GA |
az iot hub device-identity create |
Create a device in an IoT Hub. |
Extension | GA |
az iot hub device-identity delete |
Delete an IoT Hub device. |
Extension | GA |
az iot hub device-identity export |
Export all device identities from an IoT Hub to an Azure Storage blob container. |
Extension | GA |
az iot hub device-identity import |
Import device identities to an IoT Hub from a storage container blob. |
Extension | GA |
az iot hub device-identity list |
List devices in an IoT Hub. |
Extension | GA |
az iot hub device-identity parent |
Manage parent device relationships for IoT devices. |
Extension | GA |
az iot hub device-identity parent set |
Set the parent device of a target device. |
Extension | GA |
az iot hub device-identity parent show |
Get the parent device of a target device. |
Extension | GA |
az iot hub device-identity renew-key |
Renew target keys of an IoT Hub device with sas authentication. |
Extension | GA |
az iot hub device-identity show |
Get the details of an IoT Hub device. |
Extension | GA |
az iot hub device-identity update |
Update an IoT Hub device. |
Extension | GA |
az iot hub device-identity create
Create a device in an IoT Hub.
When using the auth method of shared_private_key (also known as symmetric keys), if no custom keys are provided the service will generate them for the device.
If a device scope is provided for an edge device, the value will automatically be converted to a parent scope.
az iot hub device-identity create --device-id
[--am {shared_private_key, x509_ca, x509_thumbprint}]
[--auth-type {key, login}]
[--device-scope]
[--edge-enabled {false, true}]
[--hub-name]
[--login]
[--od]
[--pk]
[--primary-thumbprint]
[--resource-group]
[--secondary-key]
[--secondary-thumbprint]
[--sta {disabled, enabled}]
[--star]
[--valid-days]
Examples
Create an edge enabled IoT device with default authorization (shared private key).
az iot hub device-identity create -n {iothub_name} -d {device_id} --ee
Create an IoT device with self-signed certificate authorization, generate a cert valid for 10 days then use its thumbprint.
az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --valid-days 10
Create an IoT device with self-signed certificate authorization, generate a cert of default expiration (365 days) and output to target directory.
az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --output-dir /path/to/output
Create an IoT device with self-signed certificate authorization and explicitly provide primary and secondary thumbprints.
az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_thumbprint --ptp {thumbprint_1} --stp {thumbprint_2}
Create an IoT device with root CA authorization with disabled status and reason.
az iot hub device-identity create -n {iothub_name} -d {device_id} --am x509_ca --status disabled --status-reason 'for reasons'
Create an IoT device with a device scope.
az iot hub device-identity create -n {iothub_name} -d {device_id} --device-scope 'ms-azure-iot-edge://edge0-123456789123456789'
Required Parameters
Target Device Id.
Optional Parameters
The authorization method an entity is to be created with.
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
The scope of the device. For edge devices, this is auto-generated and immutable. For leaf devices, set this to create child/parent relationship.
Flag indicating edge enablement.
IoT Hub name or hostname. Required if --login is not provided.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Generate self-signed cert and use its thumbprint. Output to specified target directory.
The primary symmetric shared access key stored in base64 format.
Self-signed certificate thumbprint to use for the primary thumbprint.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
The secondary symmetric shared access key stored in base64 format.
Self-signed certificate thumbprint to use for the secondary thumbprint.
Set device status upon creation.
Description for device status.
Generate self-signed cert and use its thumbprint. Valid for specified number of days. Default: 365.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity delete
Delete an IoT Hub device.
az iot hub device-identity delete --device-id
[--auth-type {key, login}]
[--etag]
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
IoT Hub name or hostname. Required if --login is not provided.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity export
Export all device identities from an IoT Hub to an Azure Storage blob container.
The output blob containing device identities is a text file named 'devices.txt'.
Permissions required - Either IoT Hub shared access policy supporting 'Registry Read & Registry Write' OR a principal with 'IoT Hub Data Contributor' role on the IoT Hub.
Storage account name and blob container name parameters can only be used when the storage account is in the same subscription as the input IoT Hub. For inline blob container SAS uri input, please review the input rules of your environment.
For more information, see https://aka.ms/iothub-device-exportimport.
az iot hub device-identity export [--auth-type {key, login}]
[--bc]
[--bcu]
[--hub-name]
[--identity]
[--ik {false, true}]
[--login]
[--resource-group]
[--sa]
Examples
Export all device identities to a configured blob container and include device keys. The blob container name and storage account name are provided as parameters to the command.
az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name}
Export all device identities to a configured blob container and include device keys. Uses an inline SAS uri example.
az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices?sv=2019-02-02&st=2020-08-23T22%3A35%3A00Z&se=2020-08-24T22%3A35%3A00Z&sr=c&sp=rwd&sig=VrmJ5sQtW3kLzYg10VqmALGCp4vtYKSLNjZDDJBSh9s%3D'
Export all device identities to a configured blob container using a file path which contains the SAS uri.
az iot hub device-identity export -n {iothub_name} --bcu {sas_uri_filepath}
Export all device identities to a configured blob container and include device keys. Uses system assigned identity that has Storage Blob Data Contributor roles for the storage account. The blob container name and storage account name are provided as parameters to the command.
az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name} --identity [system]
Export all device identities to a configured blob container and include device keys. Uses system assigned identity that has Storage Blob Data Contributor roles for the storage account. The blob container uri does not need the blob SAS token.
az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices' --identity [system]
Export all device identities to a configured blob container and include device keys. Uses user assigned managed identity that has Storage Blob Data Contributor role for the storage account. The blob container name and storage account name are provided as parameters to the command.
az iot hub device-identity export -n {iothub_name} --ik --bc {blob_container_name} --sa {storage_account_name} --identity {managed_identity_resource_id}
Export all device identities to a configured blob container and include device keys. Uses user assigned managed identity that has Storage Blob Data Contributor role for the storage account. The blob container uri does not need the blob SAS token.
az iot hub device-identity export -n {iothub_name} --ik --bcu 'https://mystorageaccount.blob.core.windows.net/devices' --identity {managed_identity_resource_id}
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
This blob container is used to output the status of the device identity import job and the results. Parameter is ignored when blob_container_uri is provided. Write, read and delete access is required for this blob container.
Blob Shared Access Signature URI with write, read, and delete access to a blob container. This is used to output the status of the job and the results. Note: when using Identity-based authentication an https:// URI is still required - but no SAS token is necessary. Input for this argument can be inline or from a file path.
IoT Hub name or hostname. Required if --login is not provided.
Managed identity type to determine if system assigned managed identity or user assigned managed identity is used. For system assigned managed identity, use [system]. For user assigned managed identity, provide the user assigned managed identity resource id. This identity requires a Storage Blob Data Contributor roles for the Storage Account.
If set, keys are exported normally. Otherwise, keys are set to null in export output.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Name of Azure Storage account containing the output blob container.Parameter is ignored when blob_container_uri is provided. Write, read and delete access is required.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity import
Import device identities to an IoT Hub from a storage container blob.
The expected input file containing device identities should be named 'devices.txt'. The output log file 'importErrors.log' is empty when import is successful and contains error logs in case of import failure.
Permissions required - Either IoT Hub shared access policy supporting 'Registry Read & Registry Write' OR a principal with 'IoT Hub Data Contributor' role on the IoT Hub.
Storage account name and blob container name parameters can only be used when the storage account is in the same subscription as the input IoT Hub. For inline blob container SAS uri input, please review the input rules of your environment.
For more information, see https://aka.ms/iothub-device-exportimport.
az iot hub device-identity import [--auth-type {key, login}]
[--hub-name]
[--ibc]
[--ibcu]
[--identity]
[--input-storage-account]
[--login]
[--obc]
[--obcu]
[--osa]
[--resource-group]
Examples
Import all device identities from a blob by providing command parameters for input blob container and storage account as well as output blob container and storage account.
az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name}
Import all device identities from a blob using an inline SAS uri.
az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri}
Import all device identities from a blob using a file path which contains SAS uri.
az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri_filepath} --obcu {output_sas_uri_filepath}
Import all device identities from a blob using system assigned identity that has Storage Blob Data Contributor roles for both storage accounts. The input blob container and storage account as well as output blob container and storage account are provided as parameters to the command
az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name} --identity [system]
Import all device identities from a blob using system assigned identity that has Storage Blob Data Contributor roles for both storage accounts. The blob container uri does not need the blob SAS token.
az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri} --identity [system]
Import all device identities from a blob using user assigned managed identity that has Storage Blob Data Contributor roles for both storage accounts. The input blob container and storage account as well as output blob container and storage account are provided as parameters to the command
az iot hub device-identity import -n {iothub_name} --ibc {input_blob_container_name} --isa {input_storage_account_name} --obc {output_blob_container_name} --osa {output_storage_account_name} --identity {managed_identity_resource_id}
Import all device identities from a blob using user assigned managed identity that has Storage Blob Data Contributor roles for both storage accounts. The blob container uri does not need the blob SAS token.
az iot hub device-identity import -n {iothub_name} --ibcu {input_sas_uri} --obcu {output_sas_uri} --identity {managed_identity_resource_id}
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
IoT Hub name or hostname. Required if --login is not provided.
This blob container stores the file which defines operations to be performed on the identity registry. Parameter is ignored when input_blob_container_uri is provided. Read access is required for this blob container.
Blob Shared Access Signature URI with read access to a blob container. This blob contains the operations to be performed on the identity registry. Note: when using Identity-based authentication an https:// URI is still required - but no SAS token is necessary. Input for this argument can be inline or from a file path.
Managed identity type to determine if system assigned managed identity or user assigned managed identity is used. For system assigned managed identity, use [system]. For user assigned managed identity, provide the user assigned managed identity resource id. This identity requires a Storage Blob Data Contributor role for the target Storage Account and Contributor role for the IoT Hub.
Name of Azure Storage account containing the input blob container.Only required when input_blob_container_uri is not provided. Read access is required.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
This blob container is used to output the status of the device identity import job and the results. Only required when input_blob_container_uri is not provided. Write access is required for this blob container.
Blob Shared Access Signature URI with write access to a blob container. This is used to output the status of the job and the results. Note: when using Identity-based authentication an https:// URI without the SAS token is still required. Input for this argument can be inline or from a file path.
Name of Azure Storage account containing the output blob container.Parameter is ignored when output_blob_container_uri is provided. Write access is required.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity list
List devices in an IoT Hub.
This command is an alias for az iot hub device-twin list
, which is highly recommended over
this command. In the future, this az iot hub device-identity list
command may be
altered or deprecated.
az iot hub device-identity list [--auth-type {key, login}]
[--edge-enabled {false, true}]
[--hub-name]
[--login]
[--resource-group]
[--top]
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
Flag indicating edge enablement.
IoT Hub name or hostname. Required if --login is not provided.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Maximum number of elements to return. Use -1 for unlimited.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity renew-key
Renew target keys of an IoT Hub device with sas authentication.
az iot hub device-identity renew-key --device-id
--hub-name
--key-type {primary, secondary, swap}
[--auth-type {key, login}]
[--etag]
[--login]
[--resource-group]
Examples
Renew the primary key.
az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt primary
Swap the primary and secondary keys.
az iot hub device-identity renew-key -d {device_id} -n {iothub_name} --kt swap
Required Parameters
Target Device Id.
IoT Hub name or hostname. Required if --login is not provided.
Target key type to regenerate.
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity show
Get the details of an IoT Hub device.
az iot hub device-identity show --device-id
[--auth-type {key, login}]
[--hub-name]
[--login]
[--resource-group]
Required Parameters
Target Device Id.
Optional Parameters
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
IoT Hub name or hostname. Required if --login is not provided.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.
az iot hub device-identity update
Update an IoT Hub device.
Use --set followed by property assignments for updating a device. Leverage parameters returned from 'iot hub device-identity show'.
az iot hub device-identity update --device-id
[--add]
[--am {shared_private_key, x509_ca, x509_thumbprint}]
[--auth-type {key, login}]
[--edge-enabled {false, true}]
[--etag]
[--force-string]
[--hub-name]
[--login]
[--pk]
[--primary-thumbprint]
[--remove]
[--resource-group]
[--secondary-key]
[--secondary-thumbprint]
[--set]
[--sta {disabled, enabled}]
[--star]
Examples
Turn on edge capabilities for device
az iot hub device-identity update -d {device_id} -n {iothub_name} --set capabilities.iotEdge=true
Turn on edge capabilities for device using convenience argument.
az iot hub device-identity update -d {device_id} -n {iothub_name} --ee
Disable device status
az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled
Disable device status using convenience argument.
az iot hub device-identity update -d {device_id} -n {iothub_name} --status disabled
In one command
az iot hub device-identity update -d {device_id} -n {iothub_name} --set status=disabled capabilities.iotEdge=true
Required Parameters
Target Device Id.
Optional Parameters
Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>
.
The authorization method an entity is to be created with.
Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. If the authentication type is login and the resource hostname is provided, resource lookup will be skipped unless needed.You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>
.
Flag indicating edge enablement.
Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.
When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.
IoT Hub name or hostname. Required if --login is not provided.
This command supports an entity connection string with rights to perform action. Use to avoid session login via "az login". If both an entity connection string and name are provided the connection string takes priority. Required if --hub-name is not provided.
The primary symmetric shared access key stored in base64 format.
Self-signed certificate thumbprint to use for the primary thumbprint.
Remove a property or an element from a list. Example: --remove property.list <indexToRemove>
OR --remove propertyToRemove
.
Name of resource group. You can configure the default group using az configure --defaults group=<name>
.
The secondary symmetric shared access key stored in base64 format.
Self-signed certificate thumbprint to use for the secondary thumbprint.
Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>
.
Set device status upon creation.
Description for device status.
Global Parameters
Increase logging verbosity to show all debug logs.
Show this help message and exit.
Only show errors, suppressing warnings.
Output format.
JMESPath query string. See http://jmespath.org/ for more information and examples.
Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID
.
Increase logging verbosity. Use --debug for full debug logs.