Verifying credentials

Cloud IoT Core offers per-device public/private key authentication using JSON Web Tokens (JWTs). For additional security, Cloud IoT Core can validate device public key certificates against registry-level Certificate Authority (CA) certificates. (This is an optional feature for additional security; you are not required to use it.)

Certificate validation allows you to verify the origin of the device credential. Each device certificate specifies its public key and information about who generated the corresponding private key. By signing the certificate, the CA attests that this key pair belongs to a legitimate device.

Verifying a certificate checks that the public key and the associated data has not been tampered with. This can be especially useful when the device manufacturer creates public and private keys, stores the private key on the device, and has the public key signed by the CA. When a registry is configured with one or more CA certificates, Cloud IoT Core certifies that device certificates are in fact signed by the associated CA. This ensures that only legitimate devices can be registered.

Certificate requirements and details

  • CA certificates must meet the following requirements:
    • X.509v3 (RFC 5280), encoded in base64, wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
    • Supported algorithms:
      • RSA with at least 2048 bits
      • NIST P-256
  • CA certificates do not need to be self-signed ("root CA").
  • Intermediary CAs are not supported; the device certificate must be signed by a specific CA certificate at the registry level.
  • Cloud IoT Core respects the certificate's validity period. If you try to add a device to a registry and the registry's certificate has expired, Cloud IoT Core returns an error.

Device requirements

When a registry has at least one CA certificate associated with it, the credentials for each new device in the registry must meet the following requirements (in addition to the standard Cloud IoT Core requirements for device credentials):

  • Device credential: X.509v3 (RFC 5280), encoded in base64, wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
  • No raw public keys
  • Supported JWT algorithms:
    • RS256
    • ES256
  • Public key signed by a registry-level CA certificate
    • The device certificate must not be identical to the registry-level certificate.
  • The certificate cannot be expired. If you try to create or update a device with an expired certificate, Cloud IoT Core returns an error.

These requirements are enforced when you create or update the device. Device public keys that are not signed by the registry-level certificates are rejected by Cloud IoT Core. If a registry does not have any CA certificates defined for it, all device public keys are unconditionally accepted.

Existing devices

Adding a CA certificate to a registry does not affect the existing devices in that registry — unless new device keys are added. If you add a new key to a device after certificates have been added to the registry, the new key will be verified against registry-level certificates.

The following table illustrates how existing devices are affected by registry-level certificates:

Timeline Result
  • Device A is created on May 15
  • Registry-level certificate is added on May 30
Device A is not affected and is not verified against registry-level certificates
Device A is updated on June 1 Device A is not affected and is not verified against registry-level certificates
A new key is added to Device A on June 3 The new key is verified against registry-level certificates

Device credentials are verified only when the device is created or updated — not when the device connects to Cloud IoT Core through either the MQTT bridge or the HTTP bridge.

Adding certificates

To use the certificate validation feature, add one or more CA certificates to the relevant device registry. A certificate can be added to multiple registries; it does not have to be exclusive to one registry.

When you add or remove certificates, existing devices in the registry (whether connected or not) are not affected. Even if a device's associated registry-level certificates are revoked, deleted, or modified, the device should still be able to connect. You can add certificates with Google Cloud Platform Console, the API, or gcloud.


  1. Go to the Registries page in GCP Console.

    Go to the Registries page

  2. At the top of the page, click Create Registry.

  3. Click Add CA certificate to type/paste a certificate or upload a certificate .pem file. You can add only one certificate when first creating the registry, but you can add more certificates later (up to 10).

The Device registry details page includes a Certificates tab that shows the existing certificates and allows you to add more.


To add or manage CA certificates, run one of the gcloud iot registries credentials commands.

To add a new certificate to a registry, run the gcloud iot registries credentials create command:

gcloud iot registries credentials create \
    --project=PROJECT_ID \
    --registry=REGISTRY_ID \


The DeviceRegistry resource includes fields for defining CA certificates at the registry level:

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud IoT Core Documentation