az iot hub device-identity

Note

This reference is part of the azure-iot extension for Azure CLI and requires version 2.17.1 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

az iot hub device-identity children

Manage IoT device's children device.

az iot hub device-identity children add

Add specified space-separated list of device ids as children of specified edge device.

az iot hub device-identity children list

Outputs list of assigned child devices.

az iot hub device-identity children remove

Remove devices as children from specified edge device.

az iot hub device-identity connection-string

Manage IoT device's connection string.

az iot hub device-identity connection-string show

Show a given IoT Hub device connection string.

az iot hub device-identity create

Create a device in an IoT Hub.

az iot hub device-identity delete

Delete an IoT Hub device.

az iot hub device-identity export

Export all device identities from an IoT Hub to an Azure Storage blob container. For inline blob container SAS uri input, please review the input rules of your environment.

az iot hub device-identity import

Import device identities to an IoT Hub from a blob. For inline blob container SAS uri input, please review the input rules of your environment.

az iot hub device-identity list

List devices in an IoT Hub.

az iot hub device-identity parent

Manage IoT device's parent device.

az iot hub device-identity parent set

Set the parent device of the specified device.

az iot hub device-identity parent show

Get the parent device of the specified device.

az iot hub device-identity renew-key

Renew target keys of an IoT Hub device with sas authentication.

az iot hub device-identity show

Get the details of an IoT Hub device.

az iot hub device-identity update

Update an IoT Hub device.

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.

az iot hub device-identity create --device-id
                                  [--am {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--auth-type {key, login}]
                                  [--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'

Required Parameters

--device-id -d

Target Device.

Optional Parameters

--am --auth-method

The authorization method an entity is to be created with.

accepted values: shared_private_key, x509_ca, x509_thumbprint
default value: shared_private_key
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

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.

--od --output-dir

Generate self-signed cert and use its thumbprint. Output to specified target directory.

--pk --primary-key

The primary symmetric shared access key stored in base64 format.

--primary-thumbprint --ptp

Self-signed certificate thumbprint to use for the primary thumbprint.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--secondary-key --sk

The secondary symmetric shared access key stored in base64 format.

--secondary-thumbprint --stp

Self-signed certificate thumbprint to use for the secondary thumbprint.

--sta --status

Set device status upon creation.

accepted values: disabled, enabled
default value: enabled
--star --status-reason

Description for device status.

--valid-days --vd

Generate self-signed cert and use its thumbprint. Valid for specified number of days. Default: 365.

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

--device-id -d

Target Device.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

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.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

az iot hub device-identity export

Export all device identities from an IoT Hub to an Azure Storage blob container. For inline blob container SAS uri input, please review the input rules of your environment.

For more information, see https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.

az iot hub device-identity export --bcu
                                  --hub-name
                                  [--auth-type {identity, key}]
                                  [--identity]
                                  [--ik {false, true}]
                                  [--resource-group]

Examples

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 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' --auth-type identity --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 roles for the storage account and contributor for the IoT hub. 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' --auth-type identity --identity {managed_identity_resource_id}

Required Parameters

--bcu --blob-container-uri

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.

--hub-name -n

IoT Hub name. Required if --login is not provided.

Optional Parameters

--auth-type --storage-authentication-type

Authentication type for communicating with the storage container.

accepted values: identity, key
--identity

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.

--ik --include-keys

If set, keys are exported normally. Otherwise, keys are set to null in export output.

accepted values: false, true
--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

az iot hub device-identity import

Import device identities to an IoT Hub from a blob. For inline blob container SAS uri input, please review the input rules of your environment.

For more information, see https://docs.microsoft.com/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities.

az iot hub device-identity import --hub-name
                                  --ibcu
                                  --obcu
                                  [--auth-type {identity, key}]
                                  [--identity]
                                  [--resource-group]

Examples

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 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} --auth-type identity --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 and contributor for the IoT hub. 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} --auth-type identity --identity {managed_identity_resource_id}

Required Parameters

--hub-name -n

IoT Hub name. Required if --login is not provided.

--ibcu --input-blob-container-uri

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.

--obcu --output-blob-container-uri

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.

Optional Parameters

--auth-type --storage-authentication-type

Authentication type for communicating with the storage container.

accepted values: identity, key
--identity

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.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

az iot hub device-identity list

List devices in an IoT Hub.

az iot hub device-identity list [--auth-type {key, login}]
                                [--edge-enabled {false, true}]
                                [--hub-name]
                                [--login]
                                [--resource-group]
                                [--top]

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

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.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--top

Maximum number of elements to return. Use -1 for unlimited.

default value: 1000

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

--device-id -d

Target Device.

--hub-name -n

IoT Hub name. Required if --login is not provided.

--key-type --kt

Target key type to regenerate.

accepted values: primary, secondary, swap

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--login -l

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.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

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

--device-id -d

Target Device.

Optional Parameters

--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

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.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

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

--device-id -d

Target Device.

Optional Parameters

--add

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>.

--am --auth-method

The authorization method an entity is to be created with.

accepted values: shared_private_key, x509_ca, x509_thumbprint
--auth-type

Indicates whether the operation should auto-derive a policy key or use the current Azure AD session. You can configure the default using az configure --defaults iothub-data-auth-type=<auth-type-value>.

accepted values: key, login
default value: key
--edge-enabled --ee

Flag indicating edge enablement.

accepted values: false, true
--etag -e

Etag or entity tag corresponding to the last state of the resource. If no etag is provided the value '*' is used.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

--hub-name -n

IoT Hub name. Required if --login is not provided.

--login -l

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.

--pk --primary-key

The primary symmetric shared access key stored in base64 format.

--primary-thumbprint --ptp

Self-signed certificate thumbprint to use for the primary thumbprint.

--remove

Remove a property or an element from a list. Example: --remove property.list OR --remove propertyToRemove.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

--secondary-key --sk

The secondary symmetric shared access key stored in base64 format.

--secondary-thumbprint --stp

Self-signed certificate thumbprint to use for the secondary thumbprint.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--sta --status

Set device status upon creation.

accepted values: disabled, enabled
--star --status-reason

Description for device status.