Share via

az iot hub module-identity

Note

This reference is part of the azure-iot extension for the Azure CLI (version 2.59.0 or higher). The extension will automatically install the first time you run an az iot hub module-identity command. Learn more about extensions.

Manage IoT device modules.

Commands

Name Description Type Status
az iot hub module-identity connection-string

Manage IoT device module's connection string.

 Extension GA
az iot hub module-identity connection-string show

Show a target IoT device module connection string.

 Extension GA
az iot hub module-identity create

Create a module on a target IoT device in an IoT Hub.

 Extension GA
az iot hub module-identity delete

Delete a device in an IoT Hub.

 Extension GA
az iot hub module-identity list

List modules located on an IoT device in an IoT Hub.

 Extension GA
az iot hub module-identity renew-key

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

 Extension GA
az iot hub module-identity show

Get the details of an IoT device module in an IoT Hub.

 Extension GA
az iot hub module-identity update

Update an IoT Hub device module.

 Extension GA

az iot hub module-identity create

Create a module on a target IoT 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 module.

az iot hub module-identity create --device-id
                                  --module-id
                                  [--am --auth-method {shared_private_key, x509_ca, x509_thumbprint}]
                                  [--auth-type {key, login}]
                                  [--hub-name]
                                  [--login]
                                  [--od --output-dir]
                                  [--pk --primary-key]
                                  [--primary-thumbprint --ptp]
                                  [--resource-group]
                                  [--secondary-key --sk]
                                  [--secondary-thumbprint --stp]
                                  [--valid-days --vd]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--am --auth-method

The authorization method an entity is to be created with.

Property Value
Default value: shared_private_key
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. 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}.

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--hub-name -n

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Parameter group: IoT Hub Identifier Arguments
--od --output-dir

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

Property Value
Parameter group: X.509 Arguments
--pk --primary-key

The primary symmetric shared access key stored in base64 format.

Property Value
Parameter group: Symmetric Key Arguments
--primary-thumbprint --ptp

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

Property Value
Parameter group: X.509 Arguments
--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.

Property Value
Parameter group: Symmetric Key Arguments
--secondary-thumbprint --stp

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

Property Value
Parameter group: X.509 Arguments
--valid-days --vd

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

Property Value
Parameter group: X.509 Arguments
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot hub module-identity delete

Delete a device in an IoT Hub.

az iot hub module-identity delete --device-id
                                  --module-id
                                  [--auth-type {key, login}]
                                  [--etag]
                                  [--hub-name]
                                  [--login]
                                  [--resource-group]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--auth-type

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

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--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 or hostname. Required if --login is not provided.

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Parameter group: IoT Hub Identifier Arguments
--resource-group -g

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

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot hub module-identity list

List modules located on an IoT device in an IoT Hub.

az iot hub module-identity list --device-id
                                [--auth-type {key, login}]
                                [--hub-name]
                                [--login]
                                [--resource-group]
                                [--top]

Required Parameters

--device-id -d

Target Device Id.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--auth-type

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

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--hub-name -n

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Default value: 1000
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot hub module-identity renew-key

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

Currently etags and key type swap are not supported for bulk key regeneration. Bulk Key regeneration will yeild a different output format from single module key regeneration.

az iot hub module-identity renew-key --device-id
                                     --hub-name
                                     --key-type --kt {both, primary, secondary, swap}
                                     --module-id
                                     [--auth-type {key, login}]
                                     [--etag]
                                     [--login]
                                     [--no-progress {false, true}]
                                     [--resource-group]

Examples

Renew the primary key.

az iot hub module-identity renew-key -m {module_name} -d {device_id} -n {iothub_name} --kt primary

Swap the primary and secondary keys.

az iot hub module-identity renew-key -m {module_name} -d {device_id} -n {iothub_name} --kt swap

Renew the secondary key for two modules.

az iot hub module-identity renew-key -m {module_name} {module_name} -d {device_id} -n {iothub_name} --kt secondary

Renew both keys for all modules in the device.

az iot hub module-identity renew-key -m * -d {device_id} -n {iothub_name} --kt both

Required Parameters

--device-id -d

Target Device Id.

--hub-name -n

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--key-type --kt

Target key type to regenerate.

Property Value
Accepted values: both, primary, secondary, swap
--module-id -m

Space seperated list of target Module Ids. Use * for all modules.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--auth-type

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

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--etag -e

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

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--no-progress

Hide the progress bar for bulk key regeneration.

Property Value
Accepted values: false, true
--resource-group -g

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

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot hub module-identity show

Get the details of an IoT device module in an IoT Hub.

az iot hub module-identity show --device-id
                                --module-id
                                [--auth-type {key, login}]
                                [--hub-name]
                                [--login]
                                [--resource-group]

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

--auth-type

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

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--hub-name -n

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Parameter group: IoT Hub Identifier Arguments
--resource-group -g

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

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False

az iot hub module-identity update

Update an IoT Hub device module.

Use --set followed by property assignments for updating a module. Leverage properties returned from 'iot hub module-identity show'.

az iot hub module-identity update --device-id
                                  --module-id
                                  [--add]
                                  [--auth-type {key, login}]
                                  [--etag]
                                  [--force-string]
                                  [--hub-name]
                                  [--login]
                                  [--remove]
                                  [--resource-group]
                                  [--set]

Examples

Regenerate module symmetric authentication keys

az iot hub module-identity update -m {module_name} -d {device_id} -n {iothub_name} --set authentication.symmetricKey.primaryKey="" authentication.symmetricKey.secondaryKey=""

Required Parameters

--device-id -d

Target Device Id.

--module-id -m

Target Module Id.

Optional Parameters

The following parameters are optional, but depending on the context, one or more might become required for the command to execute successfully.

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

Property Value
Parameter group: Generic Update Arguments
Default value: []
--auth-type

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

Property Value
Parameter group: Access Control Arguments
Default value: key
Accepted values: key, login
--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.

Property Value
Parameter group: Generic Update Arguments
Default value: False
--hub-name -n

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

Property Value
Parameter group: IoT Hub Identifier Arguments
--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.

Property Value
Parameter group: IoT Hub Identifier Arguments
--remove

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

Property Value
Parameter group: Generic Update Arguments
Default value: []
--resource-group -g

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

--set

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

Property Value
Parameter group: Generic Update Arguments
Default value: []
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

Property Value
Default value: False
--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

Property Value
Default value: False
--output -o

Output format.

Property Value
Default value: json
Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

Property Value
Default value: False