az iot adr ns ca

  • Preview

Note

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

Command group 'iot adr ns' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Manage certificate authorities for a Device Registry namespace.

Commands

Name Description Type Status
az iot adr ns ca activate

Activate an externally issued intermediate certificate authority.

 Extension Preview
az iot adr ns ca create

Create a certificate authority for a Device Registry namespace.

 Extension Preview
az iot adr ns ca delete

Delete a certificate authority from a Device Registry namespace.

 Extension Preview
az iot adr ns ca list

List the certificate authorities for a Device Registry namespace.

 Extension Preview
az iot adr ns ca policy

Manage certificate policies for a certificate authority.

 Extension Preview
az iot adr ns ca policy create

Create a certificate policy for a certificate authority.

 Extension Preview
az iot adr ns ca policy delete

Delete a certificate policy from a certificate authority.

 Extension Preview
az iot adr ns ca policy list

List the certificate policies for a certificate authority.

 Extension Preview
az iot adr ns ca policy show

Show a certificate policy for a certificate authority.

 Extension Preview
az iot adr ns ca policy update

Update a certificate policy for a certificate authority.

 Extension Preview
az iot adr ns ca policy wait

Wait for a certificate policy to reach a desired state.

 Extension Preview
az iot adr ns ca revoke

Revoke and rotate an intermediate certificate authority issued by a Microsoft CA.

 Extension Preview
az iot adr ns ca show

Show a certificate authority for a Device Registry namespace.

 Extension Preview
az iot adr ns ca update

Update a certificate authority for a Device Registry namespace.

 Extension Preview
az iot adr ns ca wait

Wait for a certificate authority to reach a desired state.

 Extension Preview

az iot adr ns ca activate

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Activate an externally issued intermediate certificate authority.

Use this after creating an ICA with --issuer-type External and signing the service-generated CSR with your external PKI. The certificate chain file must be in PEM format with certificates ordered from leaf to root. Sign the actual service CSR and preserve its requested extensions. OpenSSL x509 -req does not copy them by default: the recipe below requires an OpenSSL version supporting -copy_extensions copy and req -addext. Protect the external root private key; use this disposable test root only for testing. Remaining validity is measured at activation. Activation may be rejected when less than 365 days of validity remain, so allow margin and make sure the root covers the ICA's entire validity. Keep the extensions requested in the CSR. The CLI checks common certificate defects; the service does final validation. Without --no-wait, returns the CA once it is Active.

az iot adr ns ca activate --ca-name --name
                          --ccf --certificate-chain-file
                          --namespace --ns
                          --resource-group
                          [--acquire-policy-token]
                          [--change-reference]
                          [--no-wait]

Examples

Activate an externally issued ICA

az iot adr ns ca activate -n myExternalICA --ns myNamespace -g myResourceGroup --certificate-chain-file ./signed-chain.pem

Create a disposable ECC root, sign the service CSR, and activate (Bash; supported OpenSSL required)

(
  set -eu
  umask 077
  pki=$(mktemp -d)
  trap 'rm -f "$pki/root.key" "$pki/root.pem" "$pki/ica.csr" "$pki/ica.pem" "$pki/chain.pem"; rmdir "$pki"' EXIT
  openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -nodes \
    -keyout "$pki/root.key" -out "$pki/root.pem" -days 3650 -subj "/CN=Disposable ADR Root" \
    -addext "basicConstraints=critical,CA:TRUE,pathlen:2" \
    -addext "keyUsage=critical,keyCertSign,cRLSign"
  az iot adr ns ca create -n myExternalICA --ns myNamespace -g myResourceGroup \
    --type ICA --issuer-type External --key-type ECC
  az iot adr ns ca show -n myExternalICA --ns myNamespace -g myResourceGroup \
    --query properties.issuer.certificateSigningRequest -o tsv > "$pki/ica.csr"
  openssl req -in "$pki/ica.csr" -noout -text
  openssl x509 -req -in "$pki/ica.csr" -CA "$pki/root.pem" -CAkey "$pki/root.key" \
    -set_serial 2 -days 730 -sha384 -copy_extensions copy -out "$pki/ica.pem"
  cat "$pki/ica.pem" "$pki/root.pem" > "$pki/chain.pem"
  az iot adr ns ca activate -n myExternalICA --ns myNamespace -g myResourceGroup \
    --certificate-chain-file "$pki/chain.pem"
)

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--ccf --certificate-chain-file

Path to a PEM file containing the signed certificate chain for an externally issued ICA. Certificates must be ordered from leaf to root, match the service CSR key, and preserve requested extensions. Allow remaining-validity margin at activation; see activate help for the OpenSSL recipe and observed service constraints.

--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
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 adr ns ca create

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Create a certificate authority for a Device Registry namespace.

The certificate authority type determines the required associated properties:

  • Root: a service-managed self-signed root CA.
  • ICA with a Microsoft issuer: signed by a root CA in the same namespace. Pass the issuing CA's name with --issuer-ca-name.
  • ICA with an External issuer: signed by an external PKI. After creation the service returns a CSR; sign that CSR (do not generate a replacement ICA key) and complete activation with 'az iot adr ns ca activate'. See activate help for a complete external ECC signing recipe.
az iot adr ns ca create --ca-name --name
                        --ca-type --type {ICA, Root}
                        --namespace --ns
                        --resource-group
                        [--acquire-policy-token]
                        [--change-reference]
                        [--issuer-ca-name --issuer-certificate-authority-name]
                        [--issuer-type {External, Microsoft}]
                        [--key-type {ECC}]
                        [--location]
                        [--no-wait]
                        [--tags]

Examples

Create a service-managed root certificate authority

az iot adr ns ca create -n myRootCA --ns myNamespace -g myResourceGroup --type Root

Create a Microsoft-issued intermediate certificate authority

az iot adr ns ca create -n myMicrosoftICA --ns myNamespace -g myResourceGroup \
  --type ICA --issuer-type Microsoft --issuer-ca-name myRootCA

Create an externally issued intermediate certificate authority

az iot adr ns ca create -n myExternalICA --ns myNamespace -g myResourceGroup \
  --type ICA --issuer-type External

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--ca-type --type

The certificate authority type. Use 'Root' for a service-managed self-signed root CA or 'ICA' for an intermediate CA.

Property Value
Accepted values: ICA, Root
--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--issuer-ca-name --issuer-certificate-authority-name

Name of the same-namespace issuing root CA. Required with --issuer-type Microsoft.

--issuer-type

Issuer type for an ICA. Use 'Microsoft' for a same-namespace CA or 'External' for an external PKI.

Property Value
Accepted values: External, Microsoft
--key-type

The cryptographic key type for the certificate authority.

Property Value
Accepted values: ECC
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

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 adr ns ca delete

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Delete a certificate authority from a Device Registry namespace.

az iot adr ns ca delete --ca-name --name
                        --namespace --ns
                        --resource-group
                        [--acquire-policy-token]
                        [--change-reference]
                        [--no-wait]
                        [--yes {false, true}]

Examples

Delete a certificate authority

az iot adr ns ca delete -n myCA --ns myNamespace -g myResourceGroup

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Property Value
Accepted values: false, true
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 adr ns ca list

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

List the certificate authorities for a Device Registry namespace.

az iot adr ns ca list --namespace --ns
                      --resource-group

Examples

List certificate authorities

az iot adr ns ca list --ns myNamespace -g myResourceGroup

Required Parameters

--namespace --ns

Name of the Device Registry namespace.

--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 adr ns ca revoke

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Revoke and rotate an intermediate certificate authority issued by a Microsoft CA.

Applies only to an ICA whose issuerType is 'Microsoft'. The service revokes the current certificate and issues a replacement signed by the same root CA. Successful waited revocation returns a fresh CA resource; --no-wait returns submission only without an added completion wait or output read. Microsoft issuers may not expose status or thumbprint. Fields are returned as supplied by the service. provisioningState describes the resource operation; it does not prove that an old certificate is rejected.

az iot adr ns ca revoke --ca-name --name
                        --namespace --ns
                        --resource-group
                        [--acquire-policy-token]
                        [--change-reference]
                        [--no-wait]
                        [--yes {false, true}]

Examples

Revoke a certificate authority

az iot adr ns ca revoke -n myCA --ns myNamespace -g myResourceGroup

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--yes -y

Skip user prompts. Indicates acceptance of action. Used primarily for automation scenarios. Default: false.

Property Value
Accepted values: false, true
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 adr ns ca show

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Show a certificate authority for a Device Registry namespace.

az iot adr ns ca show --ca-name --name
                      --namespace --ns
                      --resource-group

Examples

Show a certificate authority

az iot adr ns ca show -n myCA --ns myNamespace -g myResourceGroup

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--namespace --ns

Name of the Device Registry namespace.

--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 adr ns ca update

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Update a certificate authority for a Device Registry namespace.

az iot adr ns ca update --ca-name --name
                        --namespace --ns
                        --resource-group
                        [--acquire-policy-token]
                        [--change-reference]
                        [--no-wait]
                        [--tags]

Examples

Update certificate authority tags

az iot adr ns ca update -n myCA --ns myNamespace -g myResourceGroup --tags env=prod

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--no-wait

Do not wait for the long-running operation to finish.

Property Value
Default value: False
--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

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 adr ns ca wait

Preview

Command group 'iot adr ns ca' is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Wait for a certificate authority to reach a desired state.

Without an explicit wait predicate, waits for provisioningState Succeeded.

az iot adr ns ca wait --ca-name --name
                      --namespace --ns
                      --resource-group
                      [--acquire-policy-token]
                      [--change-reference]
                      [--created]
                      [--custom]
                      [--deleted]
                      [--exists]
                      [--interval]
                      [--timeout]
                      [--updated]

Examples

Wait until certificate authority provisioning succeeds

az iot adr ns ca wait -n myCA --ns myNamespace -g myResourceGroup

Required Parameters

--ca-name --name -n

Name of the certificate authority.

--namespace --ns

Name of the Device Registry namespace.

--resource-group -g

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

Optional Parameters

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

--acquire-policy-token

Acquiring an Azure Policy token automatically for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--change-reference

The related change reference ID for this resource operation.

Property Value
Parameter group: Global Policy Arguments
--created

Wait until provisioningState is Succeeded.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--custom

Wait until a custom JMESPath expression evaluates to true.

Property Value
Parameter group: Wait Condition Arguments
--deleted

Wait until the resource is deleted.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--exists

Wait until the resource exists.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
--interval

Polling interval in seconds.

Property Value
Parameter group: Wait Condition Arguments
Default value: 30
--timeout

Polling budget in seconds, including GET time. An in-flight GET is bounded by transport timeouts and cannot be interrupted by this polling deadline.

Property Value
Parameter group: Wait Condition Arguments
Default value: 3600
--updated

Wait until provisioningState is Succeeded.

Property Value
Parameter group: Wait Condition Arguments
Default value: False
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