Device Provisioning and Authentication with PKI Tutorial

In this tutorial, you will create a Murano Product and demonstrate how a custom Certificate Authority (CA) can be configured for it. You will then provision a device with a client side certificate signed by the configured Certificate Authority. Finally, you will connect the device to Murano and successfully authenticate with the newly signed client side certificate.

Table of contents


Hardware Setup

This tutorial does not require hardware. It assumes developers will use command line CURL commands or implement in a language of choice using HTTP client library commands.

Software Setup

To complete this tutorial, you will need:

Create a Product

Assuming that you already have a business created, open the Solutions page, click on the +NEW SOLUTION button and select Add a Product from the dropdown box to create a new product. Or, if you don't already have products, you may click on the ADD PRODUCT button to do the same.

In the dialog that opens up, give your product a name and leave everything else blank or at their defaults. Click ADD.

Navigate to your newly created product's Settings page and locate the Provisioning and Public Key Infrastructure sections.

In the Provisioning section, select the TLS Client Certificate authentication method and leave everything else at their defaults. In the Public Key Infrastructure section, check the box next to Enable PKI. This will reveal a text box titled Add Client CA Cert Here. That is where you have to paste your Client CA Certificate in PEM format.

With PKI enabled, a drop-down box titled Validator Vendor Name also appears, allowing you to choose a PKI vendor to sign Certificate Signing Requests (CSR). This is optional.

If you leave it blank, devices will have to be provisioned with certificates already signed by the Certificate Authority configured as the Client CA above.

If you select a vendor, a manufacturing fixture can provision devices with Certificate Signing Requests and have Murano forward the requests to the selected vendor for signing. In this case, a set of vendor specific options appear as seen in the screenshot below:

The currently supported vendors are:

Now, click the SAVE button in the upper right corner to commit your changes to your product's settings.

At this point, you have successfully created a product, configured it to use the TLS Client Certificate authentication method and configured the Public Key Infrastructure for certificate validation and, optionally, for certificate signing.

Continue here if you HAVE NOT configured a PKI validator vendor, otherwise skip this section

In the previous session, we left the Enable Provisioning and Allow devices to register their own identity options selected. Because of that, we don't need to explicitly whitelist a device for provisioning. The device can simply connect to Murano with its client side certificate provided and Murano will automatically save the device's identity (Common Name extracted from the certificate) and certificate for subsequent authentication. On top of that, devices using TLS Client Certificate authentication, do not need to explicitly call the activate endpoint to get provisioned. Instead, they can start sending data on their first connection.

In order for a device to write data to Murano, the product endpoint needs to be known. While on the product page, click the ID icon in the top left. This will copy the product ID onto the clipboard.

Then, issue the following command using the just copied product ID pasted in place of product-endpoint. For the --cert option, use the client side certificate (signed by the configured Client CA) concatenated with the Client CA. For the --key option, use the private key.

  curl -v \
    -X POST https://<product-endpoint> \
    --cert ./client.crt \
    --key ./client.key \
    -d temp=50

The above command has now provisioned the device and wrote the value 50 with the alias "temp". Murano has verified that the provided certificate had been signed by the Client CA Certificate that is configured for this product.

Issuing the same command subsequently, will cause Murano to use the client certificate to identify (by extracting the Common Name) and authenticate the device (by verifying that the client certificate has been issued by the configured Client CA Certificate and by checking whether the provided certificate has been associated with the connecting device in Murano's database).

Continue here if you HAVE configured a PKI validator vendor

With a PKI vendor configured, Murano is ready to submit Certificate Signing Requests (CSR) to the configured vendor, using the configured credentials and options. When a device is added with its "auth.type" field set to "csr" and its "auth.key" populated with the actual CSR in PEM format, Murano will initiate the signing procedure with the configured vendor, save the returned certificate as the "auth.key" and set "auth.type" to "certificate".

That said, follow the steps below: