Move ADR certificate management to the certificate-authority model

[Ewerton Scaboro da Silva (ewertons)]

Certificate management provisioning no longer works: the ADR object model it targeted was public preview and has been replaced.

A certificate policy used to hang off a namespace credential and be referenced from an enrollment by a single name. It now hangs off an issuing CA, and an enrollment references it by three names that must travel together. The hub and DPS used to be pointed at a namespace and a shared user-assigned identity when they were created; the relationship is now expressed on the namespace, as endpoints linked to it afterwards, with each resource authenticating as its own system-assigned identity.

Changes

• Create the root -> issuing CA -> certificate policy chain, after linking, so ADR has a hub to sync the issuing CA certificate to. A policy created under a root is rejected with PolicyRequiresIssuingCa.
• Link the hub and DPS to the namespace and wait for the endpoints, retrying while the namespace identity grants replicate, and healing a namespace left Failed by an otherwise successful link.
• Write enrollments over the DPS service API, carrying the three policy names. The CLI cannot express them: it only ever offered --credential-policy, and the az iot adr group ships only in preview builds and still models the retired shape.
• Push the linked namespace into the DPS data plane with a tags-only update. Committing a link does not push scale-unit configuration, so without it every enrollment write fails with errorCode 400004.
• Skip linked-hub creation under certificate management, where ADR chooses the provisioning targets and the DPS list is read-only (IH409313).
• Read linked hubs from the namespace endpoints. They were read from the DPS resource captured before the hub is attached, so the list was always empty.
• Drop the extension version pin, the credential sync, the Contributor grant to the IoT Hub first-party application, and the Onboarding role, all of which belonged to the previous model.

TestEnvironmentInfo.AzureAdrPolicyName is replaced by AdrPolicy, and the generated test configuration exports the namespace and certificate authority names alongside ADR_CERT_MGMT_POLICY_NAME. No other file in the repository referenced the old property.

Verification

Run locally against PowerShell 7.4.6; the module parses and imports cleanly, and 37 assertions pass across two suites:

• Unit: policy reference all-or-nothing semantics, enrollment body shape, TestEnvironmentInfo JSON round-trip, and the DPS SAS token checked against an independent implementation of the same HMAC-SHA256 construction.
• Flow: the provisioning sequence driven against a stubbed CLI, asserting the three certificate authority resources are created in order with the policy under the issuing CA, the enrollment PUT goes to the service API at the ADR-aware api-version with all three policy names and no credentialPolicyName, and no retired command or flag is used.

Live provisioning against a subscription has not been run and is the remaining validation: create an environment with -EnableCertificateManagement, confirm the chain and endpoints reach Succeeded, and confirm the first enrollment write is not rejected.

[Copilot]

🟡 Changes recommended

The ADR namespace linking payload appears to use the IoT Hub endpoint type for the DPS endpoint, which is likely to break provisioning links at runtime.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the PowerShell provisioning/test module to use the post-public-preview Azure Device Registry (ADR) certificate-authority model for certificate management, replacing the previous CLI-driven ADR surface area with direct ARM + DPS service-API calls.

Changes:

• Removes the azure-iot CLI extension version pin and routes ADR operations through az rest (ARM) instead of az iot adr.
• Adds ADR provisioning/linking helpers (namespace creation, endpoint linking, CA chain + policy creation) and waits/polling utilities.
• Writes DPS enrollments via the DPS service REST API to carry the three-part ADR policy reference (namespace/CA/policy).

File summaries

File	Description
scripts/Azure.Iot.Sdk.Test.psm1	Reworks ADR certificate management provisioning and DPS enrollment creation to match the new certificate-authority model.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The updated E2E config generators dereference TestEnvInfo.AdrPolicy.* unconditionally, which will throw when certificate management isn’t enabled (AdrPolicy is null), breaking config generation for non-ADR environments.

Review details

Suppressed comments (7)

Previously missed (2) — in code that hasn't changed since the last review.

scripts/Azure.Iot.Sdk.Test.psm1:1577

• The ADR/DPS api-version constants are future-dated relative to the current date (e.g. 2026-11-02-preview). If these versions aren't available in the target cloud/subscription yet, every az rest call will fail with an invalid/unsupported api-version error. Consider allowing these to be overridden via environment variables (or module parameters) so runs can be unblocked without code changes.
  scripts/Azure.Iot.Sdk.Test.psm1:3150
• TestEnvInfo.AdrPolicy can be $null when certificate management wasn't enabled (e.g., environments created without -EnableCertificateManagement or JSON loaded from older configs). These lines dereference .NamespaceName/etc unconditionally, which will throw and prevent config generation even for non-ADR runs. Consider emitting empty strings when AdrPolicy is null (matching the previous string-based behavior).

This issue also appears in the following locations of the same file:

• line 3179
• line 3256
• line 3278
• line 3340
• line 3370

scripts/Azure.Iot.Sdk.Test.psm1:3181

• Same null-dereference issue as the PowerShell block above: this bash config generation path also assumes TestEnvInfo.AdrPolicy is non-null and will throw when it isn't. Emit empty strings when AdrPolicy is null to keep config generation working for non-ADR environments.

            "export ADR_CERT_MGMT_NAMESPACE_NAME=`"$($TestEnvInfo.AdrPolicy.NamespaceName)`""
            "export ADR_CERT_MGMT_CERTIFICATE_AUTHORITY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificateAuthorityName)`""
            "export ADR_CERT_MGMT_POLICY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificatePolicyName)`""

scripts/Azure.Iot.Sdk.Test.psm1:3258

• New-AzIotNetSDKE2ETestConfig dereferences TestEnvInfo.AdrPolicy.* unconditionally. If the environment was created without certificate management, AdrPolicy is $null and config generation will throw. Use empty strings (or conditionally omit these variables) when AdrPolicy is not set.

            "`$env:ADR_CERT_MGMT_NAMESPACE_NAME = `"$($TestEnvInfo.AdrPolicy.NamespaceName)`""
            "`$env:ADR_CERT_MGMT_CERTIFICATE_AUTHORITY_NAME = `"$($TestEnvInfo.AdrPolicy.CertificateAuthorityName)`""
            "`$env:ADR_CERT_MGMT_POLICY_NAME = `"$($TestEnvInfo.AdrPolicy.CertificatePolicyName)`""

scripts/Azure.Iot.Sdk.Test.psm1:3280

• Same null-dereference issue as the PowerShell block above: the bash path assumes TestEnvInfo.AdrPolicy is non-null and will throw otherwise. Emit empty strings when AdrPolicy is $null to preserve backward compatibility.

            "export ADR_CERT_MGMT_NAMESPACE_NAME=`"$($TestEnvInfo.AdrPolicy.NamespaceName)`""
            "export ADR_CERT_MGMT_CERTIFICATE_AUTHORITY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificateAuthorityName)`""
            "export ADR_CERT_MGMT_POLICY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificatePolicyName)`""

scripts/Azure.Iot.Sdk.Test.psm1:3342

• New-AzIotPythonSDKE2ETestConfig dereferences TestEnvInfo.AdrPolicy.* unconditionally. If AdrPolicy is $null (non-certificate-management environment), this will throw and block config generation. Consider emitting empty strings when AdrPolicy is not present.

            "`$env:ADR_CERT_MGMT_NAMESPACE_NAME = `"$($TestEnvInfo.AdrPolicy.NamespaceName)`""
            "`$env:ADR_CERT_MGMT_CERTIFICATE_AUTHORITY_NAME = `"$($TestEnvInfo.AdrPolicy.CertificateAuthorityName)`""
            "`$env:ADR_CERT_MGMT_POLICY_NAME = `"$($TestEnvInfo.AdrPolicy.CertificatePolicyName)`""

scripts/Azure.Iot.Sdk.Test.psm1:3372

• Same null-dereference issue as the PowerShell block above: this bash block also assumes TestEnvInfo.AdrPolicy is non-null and will throw otherwise. Emit empty strings when AdrPolicy is $null.

            "export ADR_CERT_MGMT_NAMESPACE_NAME=`"$($TestEnvInfo.AdrPolicy.NamespaceName)`""
            "export ADR_CERT_MGMT_CERTIFICATE_AUTHORITY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificateAuthorityName)`""
            "export ADR_CERT_MGMT_POLICY_NAME=`"$($TestEnvInfo.AdrPolicy.CertificatePolicyName)`""

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Ewerton Scaboro da Silva (ewertons)]

Addressed both points from the second review in 4fdd94c.

Null AdrPolicy in the config generators. Confirmed: it renders as empty strings normally but throws under Set-StrictMode -Version 3.0, so the risk is real. Rather than guard twelve call sites, an environment now always carries a reference and it is simply incomplete when certificate management is off. Callers already gate on IsComplete(), so the emitted values match the previous empty-string behaviour. Covered by a test that renders the three names under StrictMode.

Future-dated api-versions. These are the versions the certificate-authority model exists at, so they cannot be lowered, but they are now overridable via ADR_API_VERSION, DPS_CONTROL_PLANE_API_VERSION and DPS_ENROLLMENT_API_VERSION so a cloud or region where one is not registered can be unblocked without a code change.

[Copilot]

🔵 Needs a closer look

It makes large, high-impact changes to live Azure provisioning behavior (preview ARM api-versions, role/linking sagas, and DPS service-API enrollment writes) that require human validation in a real subscription.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

There is a confirmed null-dereference bug in the new ARM provisioning-state wait loop, and the default ADR/DPS API versions are dated in the future and may break provisioning without overrides.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

scripts/Azure.Iot.Sdk.Test.psm1:501

• Wait-AzProvisioningState calls (Invoke-AzRest -AllowFailure).properties.provisioningState directly. When Invoke-AzRest returns $null (any transient ARM/CLI failure), this will throw a null-reference and abort the wait loop, defeating the purpose of -AllowFailure.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Ewerton Scaboro da Silva (ewertons)]

Addressed the latest review in 80b9b3f.

Null dereference in Wait-AzProvisioningState. Valid. Confirmed the behaviour: $null.properties.provisioningState yields $null normally but throws under Set-StrictMode -Version 3.0, and either way reading the state straight off a call that was explicitly allowed to fail contradicted the intent. A failed read is now an unknown state for that attempt, and the wait continues against its deadline. Covered by a test that fails the first read and requires the wait to still settle.

Future-dated api-versions. These cannot be lowered: the certificate-authority resource tree exists only at 2026-11-02-preview and later, which is the whole reason for this change; the earlier versions expose the retired model. They are overridable via ADR_API_VERSION, DPS_CONTROL_PLANE_API_VERSION and DPS_ENROLLMENT_API_VERSION for a cloud or region where one is not registered.

Local verification: module parses and imports, 43 assertions pass across the unit and flow suites. Live provisioning against a subscription remains the outstanding validation, as noted in the description.

[Copilot]

🔵 Needs a closer look

The defaults include future-dated api-version strings and there is at least one reliability issue around masking az extension update failures that should be addressed before merging.

Review details

Suppressed comments (1)

scripts/Azure.Iot.Sdk.Test.psm1:167

• Install-AzureIotCliExtension unconditionally suppresses az extension update stderr and then forces $LASTEXITCODE = 0. This hides real update failures (e.g., transient network issues, extension install corruption), which can later surface as confusing provisioning errors while the log claims the extension was updated. It’s safer to ignore only the known "already up to date" failure mode and fail fast for other errors.

        # Already up to date is reported as a failure, so the exit code is reset rather than checked.
        Write-Host "Azure IoT extension $($Extension.version) found; updating."
        az extension update --name azure-iot --only-show-errors 2>$null | Out-Null
        $global:LASTEXITCODE = 0

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Ewerton Scaboro da Silva (ewertons)]

Addressed in 8fac417.

Masked az extension update failures. Correct, and my justifying comment was simply wrong. Checked the CLI source: when no newer version is available update_extension hits NoExtensionCandidatesError, logs a warning and returns, so the command exits successfully. Being already up to date was never reported as a failure, so the suppression bought nothing and only hid real errors. Both the redirect and the exit-code reset are gone; it now fails fast via Stop-OnError.

Future-dated api-versions. As above, these cannot be lowered without reverting to the retired model, and all three are overridable from the environment.

[Copilot]

🔵 Needs a closer look

There are confirmed null-handling bugs in tags-only PATCH flows (which can break reconciliation/dataplane sync) and a polling robustness issue that can fail provisioning on transient ARM reads.

Review details

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

scripts/Azure.Iot.Sdk.Test.psm1:1704

• Connect-AdrNamespace polls for endpoint linkingState for up to 15 minutes, but a single transient failure to read the namespace via Invoke-AzRest will currently stop provisioning immediately. This is inconsistent with Wait-AzProvisioningState, which treats transient ARM/CLI read failures as non-fatal during polling.
  scripts/Azure.Iot.Sdk.Test.psm1:1732
• In the namespace reconciliation path, $Namespace.tags can be $null when the resource has no tags; calling .PSObject.Properties on $null will throw and prevent recovery from provisioningState=Failed. Guard the tag enumeration so the reconcile PATCH always succeeds.

This issue also appears on line 1834 of the same file.

scripts/Azure.Iot.Sdk.Test.psm1:1837

• Sync-DpsAdrConfiguration builds $Tags by enumerating (Invoke-AzRest ...).tags.PSObject.Properties, but .tags can be $null when no tags are set, causing the best-effort sync to always fail early (and skip the PATCH that triggers the dataplane push). Guard the tag enumeration so the PATCH is attempted even with no existing tags.

    try {
        $Tags = @{}
        (Invoke-AzRest -Url $Url).tags.PSObject.Properties | %{ $Tags[$_.Name] = $_.Value }
        $Tags["AdrDataplaneSyncUtc"] = (Get-Date).ToUniversalTime().ToString("o")

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Ewerton Scaboro da Silva (ewertons)]

Live-validated against the C SDK CSR e2e pipeline (ci-c-e2e-csr, cert-management provisioning, centraluseuap), 19 runs. Not yet green; progress and the remaining blocker below.

Baseline. That pipeline was already failing on every run against master, at az iot dps create --ns-resource-id with IH500019 — the failure this PR exists to fix.

Fixed and confirmed by the service, in order of discovery:

1. az iot dps create --mi-system-assigned is preview-only; the stable extension rejects it. DPS identity is set through ARM at creation (it cannot be patched later — IH400158).
2. 2026-11-02-preview is not registered for namespaces in eastus; it is in centraluseuap.
3. Custom role for certificate issuance hit RoleDefinitionLimitExceeded. Not needed — built-in Azure Device Registry Contributor already carries the issueCertificate data action.
4. An S1 hub is not linkable. Certificate management needs a GEN2 hub, whose --sku GEN2 / --ns-resource-id arguments are preview-only, so the extension pin is restored — for the hub, not for the retired az iot adr group.
5. A GEN2 hub built from a plain ARM request is accepted and then settles at state=ActivationFailed; the CLI call produces a working one.
6. Ordering: ADR refuses a messaging endpoint unless the namespace already has a provisioning one, so the DPS is attached before the hub is created, and every endpoint must carry inboundCallerIdentity.

Remaining blocker. Attaching the DPS as a provisioning endpoint fails 12 times over 12 minutes with:

LinkableResourceNotReady: The linked resource ".../provisioningServices/<dps>" could not be read and may not be ready. Verify it is available, then resubmit the request.

The DPS is provisioningState=Succeeded before linking. The namespace identity holds Contributor on the DPS and the DPS identity holds Contributor + Azure Device Registry Contributor on the namespace, and both are waited for until readable, so this does not look like propagation.

Open question for whoever owns the service: how is a DPS meant to be attached to an ADR namespace in this build — as a namespace provisioning endpoint as here, or still at DPS creation time? If at creation, IH500019 from the baseline needs explaining, since the namespace was valid at that point.

The provisioning changes up to that point are validated. The branch is not ready to merge until the DPS attach works.

[Ewerton Scaboro da Silva (ewertons)]

Converged the provisioning onto the reference E2E harness for this feature rather than continuing to patch it. That was the right call and fixed several things, but the remaining blocker turns out to be environmental, not scripted.

Now matched to the reference (each had been a divergence of mine):

• namespace carries the useMiSdk tag the harness sets;
• plain S1 hub with a system-assigned identity, not GEN2 with the namespace in its properties;
• hub and DPS attached in one link, both endpoints together, every endpoint carrying inboundCallerIdentity;
• DPS control-plane calls routed to the regional host in canary locations, where its linking manifest is registered (and the token audience stated explicitly, or the regional host gets no auth header);
• namespace recreated and re-granted if the in-place link retries exhaust.
• The extension version pin is gone again: every ADR resource, and both resources in the link, are created through ARM.

Blocker. hub-1 still fails LinkableResourceNotReady ("could not be read") across 24 attempts and two freshly-created namespaces, roughly 35 minutes. Provider state in the subscription this pipeline runs in:

• Microsoft.Devices registered preview features: none.
• IotHubs api-versions stop at 2026-05-01-preview; the harness uses 2026-06-01-preview, which is not offered here.

So the IoT Hub resource provider in this subscription has no ADR-linking surface, which is also why the original az iot dps create --ns-resource-id failed IH500019 on master. No change to this module can work around that.

Needed: the ADR-linking preview feature registered on Microsoft.Devices for the subscription this pipeline uses, or the pipeline pointed at one that already has it. Happy to re-run once either is in place.

Local gates green throughout. Not ready to merge until the link succeeds end to end.

[Copilot]

🟡 Changes recommended

There is at least one confirmed runtime-breaking bug (missing Location parameter usage) plus a security posture regression risk (min TLS not set) that should be addressed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 4
• Review effort level: Lite

[Ewerton Scaboro da Silva (ewertons)]

Correct, and a real one. $Location was never bound, so Get-DpsArmHost received an empty value and returned the global host — the data-plane push went to the wrong host in exactly the canary locations the regional host exists for, silently rather than throwing. Parameter declared in c9937bd; the call site was already passing it.

[Ewerton Scaboro da Silva (ewertons)]

Agreed, fixed in c9937bd. The certificate-management hub now sets minTlsVersion = "1.2" like every other hub here instead of relying on the default. It was omitted while the hub was briefly GEN2 and being minimised to isolate an activation failure; the hub is plain S1 again, so there is no reason to leave it off.

[Ewerton Scaboro da Silva (ewertons)]

Right, removed in c9937bd. It became unused when the hub stopped reaching the namespace as its own identity; nothing is granted that role any more.

[Ewerton Scaboro da Silva (ewertons)]

Correct, the description was stale, fixed in c9937bd. It described an earlier arrangement that attached the DPS first and let the hub attach itself. Both endpoints now go in one write, because ADR refuses a messaging endpoint unless the namespace also has a provisioning one, and the description says so.

[Ewerton Scaboro da Silva (ewertons)]

Answering the question directly: nothing in the module differs from the reference any more. The difference is the subscription.

Measured, not inferred:

	Reference / feature owners	This CSR pipeline
Subscription	53cd450b-… IOTDPS_TEST_DEV_1	aziotclb - Build System subscription
Identity	service connection iot-dps-arm-test-mi	the SDK build OIDC identity
Region	centraluseuap	centraluseuap (set on the test branch)

The owners' pipeline hardcodes that subscription, and their harness documents it as the default and as a prerequisite (Contributor + User Access Administrator on it).

The pipeline identity can see exactly one subscription — the build subscription — and az account set on the DPS test subscription returns "doesn't exist in cloud 'AzureCloud'", i.e. no access. In that build subscription:

• Microsoft.Devices registered preview features: none;
• IotHubs api-versions stop at 2026-05-01-preview.

So the IoT Hub resource provider there has no ADR-linking surface, which is why hub-1 reports LinkableResourceNotReady across 24 attempts and two freshly created namespaces, and why the original az iot dps create --ns-resource-id failed IH500019 on master. The reference is sufficient for its owners because it runs where that surface exists.

Ask, either one:

1. enable the ADR-linking preview on Microsoft.Devices in the build subscription; or
2. give this pipeline's identity Contributor + User Access Administrator on 53cd450b-… and point AZURE_SUBSCRIPTION_ID at it.

Test branch test/adr-cert-authority-psm1 in the SDK repo is reset to just two changes (psm1 URL, region) and re-runs clean once either is in place.

[Copilot]

🔵 Needs a closer look

It makes substantial changes to live Azure provisioning/linking behavior (including new ARM/DPS REST flows) and the PR notes live subscription validation is still outstanding.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

scripts/Azure.Iot.Sdk.Test.psm1:1814

• The reconcile path comment says the namespace is created without tags, but New-AdrNamespace always sets tags = $script:AdrNamespaceTags. The guard itself is fine, but the rationale is now misleading; please update it to reflect that tags may be absent on some namespaces (e.g., pre-existing ones) rather than on those created by this module.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite