Dps device registration using device sdk

[vilit1]

Support DPS device registration using the Device sdk (https://github.com/Azure/azure-iot-sdk-python)

Note that this will just register a device using the DPS and it should end up in IoT Hub. Since the HTTP protocol for device registration is not as "stable" as the mqtt pipeline in the device sdk, the device sdk is used.

Key usability improvements:

1. Can retrieve the id scope
2. Can retrieve the symmetric key or generate device key
3. If the id scope and symmetric key/device key is provided, can avoid any az login attempts.

Note that there are a lot of "fixes" and "add-ons" for this:

1. The return type from the device sdk registration is manually created. The device sdk registration state's string format does not adhere to our purposes.
2. Error handling involves error matching and changing the error message to be more understandable.

Some x509 limitations discovered:

• the registration id for individual enrollments must be the same as the subject: https://docs.microsoft.com/en-us/azure/iot-dps/concepts-service#individual-enrollment
• group id is not needed for group enrollments - the registration id is only used.

Help Page in question:

Command
    az iot device registration create : Register an IoT Device with IoT Device Provisioning Service.
        The following attestation mechanisms are supported:
        - Symmetric key
        - x509 certificate
        If using x509 authentication methods, the certificate and key files must be provided.
        Command group 'iot device registration' is in preview and under development. Reference
        and support levels: https://aka.ms/CLI_refstatus

Arguments
    --registration-id --rid     [Required] : Device registration ID or individual enrollment ID.
    --enrollment-group-id --gid --group-id : Enrollment group ID.
    --payload                              : Custom allocation payload as JSON. Specifically for use
                                             with custom allocation policies using Azure Functions.
    --resource-group -g                    : Name of resource group. You can configure the default
                                             group using `az configure --defaults group=<name>`.

Access Control Arguments
    --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>`.  Allowed
                                             values: key, login.  Config: key.

Device Provisioning Service Identifier Arguments
    --dps-name -n                          : Name of the Azure IoT Hub Device Provisioning Service.
                                             Required if --login is not provided or authenticaton
                                             arguments and --id-scope are not provided.
    --id-scope --scope                     : Id Scope of the Azure IoT Hub Device Provisioning
                                             Service. If provided with authentication arguments,
                                             will avoid session login.
    --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 --dps-name is not provided or authenticaton
                                             arguments and --id-scope are not provided.

Symmetric Key Authentication Arguments
    --ck --compute-key                     : Flag to indicate that the symmetric key for the device
                                             registration should be computed from the given key with
                                             --symmetric-key.
    --key --symmetric-key                  : The symmetric shared access key for the device
                                             registration.

x509 Authentication Arguments
    --certificate-file-path --cp           : Path to certificate PEM file. Required for x509
                                             registrations.
    --key-file-path --kp                   : Path to key PEM file. Required for x509 registrations.
    --pass --passphrase                    : Passphrase for the certificate.

Global Arguments
    --debug                                : Increase logging verbosity to show all debug logs.
    --help -h                              : Show this help message and exit.
    --only-show-errors                     : Only show errors, suppressing warnings.
    --output -o                            : Output format.  Allowed values: json, jsonc, none,
                                             table, tsv, yaml, yamlc.  Default: json.
    --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.

Examples
    Register an IoT Device using an individual enrollment.
        az iot device registration create -n {dps_name} --rid {registration_id}

    Register an IoT Device using a group enrollment.
        az iot device registration create -n {dps_name} --rid {registration_id} --gid
        {group_enrollment_id}

    Register an IoT Device using an individual enrollment, the Device Provisioning Service ID Scope,
    and given symmetric key. This will bypass retrieving the ID Scope and individal enrollment
    symmetric key.
        az iot device registration create --id-scope {id_scope} --rid {registration_id} --key
        {symmetric_key}

    Register an IoT Device using a group enrollment, the Device Provisioning Service ID Scope, and
    given enrollment group symmetric key. This will bypass retrieving the ID Scope and enrollment-
    group symmetric key. The symmetric key used for the device registration will be computed from
    the given symmetric key.
        az iot device registration create --id-scope {id_scope} --rid {registration_id} --gid
        {group_enrollment_id} --key {symmetric_key} --ck

    Register an IoT Device using a group enrollment, the Device Provisioning Service ID Scope, and
    given symmetric key. This will bypass retrieving the ID Scope. Note that since the symmetric key
    should be the computed device key, the enrollment group id is not needed.
        az iot device registration create --id-scope {id_scope} --rid {registration_id} --key
        {symmetric_key}

    Register an IoT Device using an individual enrollment, the Device Provisioning Service ID Scope,
    and given certificate and key files. This will bypass retrieving the ID Scope.
        az iot device registration create --id-scope {id_scope} --rid {registration_id} --cp
        {certificate_file} --kp {key_file}

    Register an IoT Device using a group enrollment, the Device Provisioning Service ID Scope, and
    given certificate and key files. This will bypass retrieving the ID Scope. Note that the group
    enrollment id is not needed for x509 attestations.
        az iot device registration create --id-scope {id_scope} --rid {registration_id} --cp
        {certificate_file} --kp {key_file}

Comparison between using a generated sdk (http transport) vs the device sdk: Generated sdk:

1. error messages are directly from service and most usable for us
2. object returned does not need any transforms and the substatus is correctly reported
3. can implement registration show - which main benefit would be to show the registration state using idscope
4. can implement registration operation show - which can show an old state of the registration
5. tokenization on service side means that only one token can be used for 30 minutes. If the primary token is used, the secondary token cannot be used until the 30 min is up (even if the enrollment is deleted).

Device sdk:

1. has support for x509 and symmetric key
2. already used for central testing
3. no tokenization issues

Future plans: support tpm attestation

---

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Thank you for contributing to the IoT extension!

This checklist is used to make sure that common guidelines for a pull request are followed.

General Guidelines

Intent for Production

• [ ] It is expected that pull requests made to default or core branches such as dev or main are of production grade. Corollary to this, any merged contributions to these branches may be deployed in a public release at any given time. By checking this box, you agree and commit to the expected production quality of code.

Basic expectations

• [ ] If introducing new functionality or modified behavior, are they backed by unit and/or integration tests?
• [ ] In the same context as above are command names and their parameter definitions accurate? Do help docs have sufficient content?
• [ ] Have all the relevant unit and integration tests pass? i.e. pytest <project root> -vv. Please provide evidence in the form of a screenshot showing a succesful run of tests locally OR a link to a test pipeline that has been run against the change-set.
• [ ] Have linter checks passed using the .pylintrc and .flake8 rules? Look at the CI scripts for example usage.
• [ ] Have extraneous print or debug statements, commented out code-blocks or code-statements (if any) been removed from the surface area of changes?
• [ ] Have you made an entry in HISTORY.rst which concisely explains your user-facing feature or change?

Azure IoT CLI maintainers reserve the right to enforce any of the outlined expectations.

A PR is considered ready for review when all basic expectations have been met (or do not apply).

[digimaun]

Let's add a HISTORY entry for this functionality

[vilit1]

https://dev.azure.com/azureiotdevxp/aziotcli/_build/results?buildId=5794&view=results - with durations

[vilit1]

hub seems to be unaffected by the sha change. https://dev.azure.com/azureiotdevxp/aziotcli/_build/results?buildId=5798&view=results

[avagraw]

As discussed - test performance improvements will be tackled as a follow up task: https://msazure.visualstudio.com/One/_sprints/taskboard/IoT-Platform-UPX/One/Custom/IoT/2206?workitem=14713177