MQTT device connection fails with custom authentication in IoT Core

IoT Google Cloud IoT
, , , , , , , ,
1

We’re experiencing authentication failures after updating our IoT Core custom authentication handler. Devices using MQTT can’t connect after a recent policy update.

The custom auth handler validates device credentials against our internal directory, but the new policy syntax seems incompatible with our credential mapping logic:


Error: MQTT connection refused (5)
auth_handler: credential_mapping failed
policy_version: 2025-01-15

Devices were connecting fine with the old policy format. The credential mapping worked perfectly for months. Now we’re blocked from onboarding new devices and existing ones can’t reconnect after network drops. Has anyone dealt with policy syntax changes affecting MQTT custom auth?

2

I ran into similar issues last month. The policy syntax changed significantly in the January update. Check if your custom auth handler is using the old attribute mapping format. The new syntax requires explicit namespace declarations for custom attributes.

3

Adding to Lisa’s point - make sure your policy includes the new ‘deviceCredentialScope’ field. Without it, the auth handler can’t properly map credentials to device identities. I’ve seen this exact error when the scope is missing or set incorrectly.

4

This looks like a credential mapping mismatch. The error code 5 indicates authorization failure, not authentication. Your MQTT broker is rejecting the connection after initial auth succeeds. I’d verify that your custom auth handler is returning the correct device identity format. The new policy expects a fully qualified device path including registry and region. Also check if your handler is setting the required IAM permissions in the response token.

5

Thanks for the insights. I checked our auth handler and it’s still using the old attribute format. Sarah, can you share what namespace declarations are now required? We’re mapping custom fields like division_id and asset_type to device metadata.

6

I had the same blocking issue two weeks ago. Here’s what you need to verify for each focus area:

MQTT Custom Auth Handler Updates: Your handler needs to return the new response format. Update your credential validation to include namespace-prefixed attributes and the device path in the correct format.

Policy Syntax Changes: The critical change is adding the deviceCredentialScope and namespacePrefix fields to your policy. Here’s the corrected structure:


policy:
  version: "2025-01-15"
  deviceCredentialScope: "registry"
  namespacePrefix: "com.yourorg"
  customAttributes:
    - "com.yourorg.division_id"
    - "com.yourorg.asset_type"

Device Credential Mapping: Update your auth handler to construct the device identity using the full path format: projects/{project}/locations/{region}/registries/{registry}/devices/{device-id}. The old short-form device IDs no longer work with custom auth.

Test with a single device first. I also recommend implementing exponential backoff in your device firmware for connection retries - we were seeing connection storms during the migration that impacted our Pub/Sub quotas.

One gotcha: if you’re using certificate-based auth alongside custom auth, make sure the certificate CN matches the device ID format expected by your handler. We had devices that passed cert validation but failed custom auth because of this mismatch.

After making these changes, our connection success rate went from 12% back to 99.7%. The migration took about 3 hours including testing.