Connecting client devices to an Amazon IoT Greengrass Core device with an MQTT broker - Amazon IoT Greengrass
Using your own CA
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Connecting client devices to an Amazon IoT Greengrass Core device with an MQTT broker

When you use an MQTT broker on your Amazon IoT Greengrass Core device, the device uses a core device certificate authority (CA) unique to the device to issue a certificate to the broker for making mutual TLS connections with clients.

Amazon IoT Greengrass will autogenerate a core device CA, or you can provide your own. The core device CA is registered with Amazon IoT Greengrass when the Client device auth component is connected. The autogenerated core device CA is persistent, the device will continue to use the same CA as long as the client device auth component is configured.

When the MQTT broker starts, it requests a certificate. The client device auth component issues an X.509 certificate using the core device CA. The certificate is rotated when the broker starts, when the certificate expires, or when connectivity information such as the IP address changes. For more information, see Certificate rotation on the local MQTT broker.

To connect a client to the MQTT broker, you need the following:

  • The client device must have the Amazon IoT Greengrass Core device CA. You can get this CA through cloud discovery, or by providing the CA manually. For more information, see Using your own certificate authority.

  • The fully-qualified domain name (FQDN) or IP address of the core device must be present in the broker certificate issued by the core device CA. You ensure this using the IP detector component or manually configuring the IP address. For more information, see Manage core device endpoints.

  • The client device auth component must give the client device permission to connect to the Greengrass core device. For more information, see Client device auth.

Using your own certificate authority

If your client devices can't access the cloud to discover your core device, you can provide a core device certificate authority (CA). Your Greengrass core device uses the core device CA to issue certificates for your MQTT broker. Once you configure the core device and provision your client device with its CA, your client devices can connect to the endpoint and verify the TLS handshake using the core device CA (own provided CA or autogenerated).

To configure the Client device auth component to use your core device CA, set the certificateAuthority configuration parameter when you deploy the component. You must provide the following details during configuration:

  • The location of a core device CA certificate.

  • The private key of the core device CA certificate.

  • (Optional) The certificate chain to the root certificate if the core device CA is an intermediate CA.

If you provide a core device CA, Amazon IoT Greengrass registers the CA with the cloud.

You can store your certificates in a hardware security module or on the file system. The following example shows a certificateAuthority configuration for a intermediate CA stored using HSM/TPM. Note that the certificate chain can only be stored on disk.

  "certificateAuthority": {
      "certificateUri": "pkcs11:object=CustomerIntermediateCA;type=cert",
      "privateKeyUri": "pkcs11:object=CustomerIntermediateCA;type=private"
      "certificateChainUri": "file:///home/ec2-user/creds/certificateChain.pem",
    }

In this example, the certificateAuthority configuration parameter configures the client device auth component to use an intermediate CA from the file system:

  "certificateAuthority": {
      "certificateUri": "file:///home/ec2-user/creds/intermediateCA.pem",
      "privateKeyUri": "file:///home/ec2-user/creds/intermediateCA.privateKey.pem",
      "certificateChainUri": "file:///home/ec2-user/creds/certificateChain.pem",
    }

To connect the devices to your Amazon IoT Greengrass Core device, do the following:

  1. Create an intermediate certificate authority (CA) for the Greengrass core device using your organization's root CA. We recommend that you use an intermediate CA as a security best practice.

  2. Provide the intermediate CA certificate, private key, and the certificate chain to your root CA to the Greengrass core device. For more information, see Client device auth. The intermediate CA becomes the core device CA for the Greengrass core device, and the device registers the CA with Amazon IoT Greengrass.

  3. Register the client device as an Amazon IoT thing. For more information, see Create a thing object in the Amazon IoT Core Developer Guide. Add the private key, public key, device certificate, and root CA certificate to your client device. How you add the information depends on your device and software.

Once you configure your device, you can use the certificate and public key chain to connect to the Greengrass core device. Your software is responsible for finding the core device endpoints. You can set the endpoint manually for the core device. For more information, see Manually manage endpoints.