Device Provisioning Tutorial

In this tutorial, you will create a Murano Product and demonstrate how to whitelist and provision devices. The tutorial covers the Murano UI as well as how to use APIs to accomplish the same thing in a manufacturing automation process. It will cover provisioning using either token-based authentication or TLS client certificates.


Software Setup

To complete this tutorial you will need:

Notational Conventions

This document uses the following notational conventions:

Getting Started

The concept of "provisioning" a device roughly outlines the process of authorizing a device to access and modify the resources and content of a particular Murano Product. Provisioning devices of a given Product can be done with several variations on prescribing the process.

This tutorial covers two of these variations separately by splitting up an optional "whitelisting" step from the "provisioning" step. Depending on your Product Settings, devices may or may not need to be whitelisted.

Configure Device Identity Format

Determine the format of your device identities and configure the new Product according to the chosen format.

A device identity uniquely identifies each device of a given product. For example, you might configure a device identity to reflect the serial number scheme in your hardware manufacturing process (e.g. 00:14:22:01:23:45, 651b3b4d-5bf3-446d-9fd0-bacdc7bfbfff, 000001, etc.).

  1. Navigate to your Solutions List and click the Product link you created for this tutorial.


  2. Click the SETTINGS menu item.


  3. For now, retain the default authentication method (token based) and leave Allow development devices to connect unchecked as all the MuranoCLI commands in this tutorial are made over a secure connection (HTTPS). Next, scroll down to the Provisioning section.


  4. Configure the chosen identity format for the product. There are a few things that may be configured for the identity format:

    • An optional Prefix for all identities. If not left blank, all identities must begin with this prefix in order to authenticate. If your device uses its wlan0 interface's MAC address as its identity, you would not need to choose a prefix unless it prepends a number of characters to the MAC address. For instance, if the MAC address is 00:00:00:01:23:45, but it's identity is CC3220-00:00:00:01:23:45 then the Prefix would be CC3220-.
    • An identifier Type. This may a number or various MAC address formats if you are using, for example, the MAC address from a WiFi chip to uniquely identify each device. It also may be in UUIDv4 format or an opaque string of characters, meaning that it has no required format.
    • A Length, if a specific length is required. Leave this blank if you want the length to be unlimited. The length of a specified Prefix does not factor in to the Length of the device identity (e.g. if Prefix=ABC and device_id=ABC123, then Length=3).
  5. Verify the box that says Allow devices to register their own identity is unchecked. This option specifies that device identities either do, or do not, need to be whitelisted in the Product before they connect. Leaving this option unchecked means we will prescriptively define which device identities are allowed to connect, authenticate and communicate. If this option was checked, devices will be provisioned with the identity that they present to Murano when connecting for the first time. For now, leave this unchecked.

  6. Leave the box that says Restrict IP addresses... unchecked. This feature may be used to provision devices from a manufacturing facility that has a specfic set of IP addresses.


  7. Click "SAVE". You have now configured the provisioning settings for your product. Next you will whitelist some devices and provision them.

Whitelisting Devices

There are several ways to whitelist devices. This tutorial will show how to whitelist one at a time, or in bulk with a file containing the identities.

Whitelist One Device At A Time Using The UI

  1. Click the DEVICES tab and then click "+ NEW DEVICE(S)" and "Add one device".


  2. Enter a serial number that conforms to the Identity Format you chose, above. For the sake of the tutorial it will be assumed that the chosen identity format is Base 10 with a length of 8. The identity entered in this box must conform to that format. Notice, too, there is a default activation period of 48 hours. This means the device must be provisioned within 48 hours of being whitelisted.


  3. Click "ADD" to create the device. You will see the device listed in a whitelisted status indicated by the tag icon on the left side of the device listing.

    (Tip: The filter tooltip menu provides a list of device status icons and their meanings.)

Whitelist Devices In Bulk Using The UI

  1. You may whitelist several devices at once. Create a text file called identities.csv with the following content:
ID,TLS Client Certificate

Note: The file is in Comma Separated Value (CSV) format, and the second column is intentionally left blank. If you do not wish to create this file, you may download the example here: identities.csv

  1. Click "+ NEW DEVICE(S)" and then "Add many devices".


  2. Click "UPLOAD CSV", navigate to the identities.csv file, and click "ADD". Now additional devices are whitelisted.


Whitelist Devices Using MuranoCLI

  1. You may whitelist a device with the MuranoCLI tool.
murano device enable 00000001

Whitelist Devices In Bulk Using MuranoCLI

  1. You may whitelist devices in bulk with the MuranoCLI tool. The murano command line tool takes a different format as input to its bulk whitelisting feature. More information can be found in the murano device enable --help dialog, but the example identities.txt file, below, can be used for this tutorial:


    Next, use this identities.txt file in the whitelisting command:

    murano device enable --file identities.txt

Provisioning Devices

Once your device identities have been whitelisted, there is a set window of time before they expire (default: 24 hours) and they may no longer provision themselves (a security feature).

Provision A Whitelisted Device (Token Authentication)

Provisioning a device with the Allow devices to register their own identity Product configuration setting enabled means that your device will appear in the Devices tab of the Product UI once it connects for the first time. Because this tutorial is using the token method of authentication, the first connection the device makes must be to activate itself which retrieves its token that is used in all subsequent HTTP Data API methods (e.g. read, write, record, etc.).

NOTE: this step is only necessary for products that use token authentication. For TLS Client Certificate, please see that section below.

Provisioning a whitelisted device using Token Authentication is done once. The result of provisioning a device using token-auth is a 40 character token that must be used by the device in the X-Exosite-CIK HTTP header in all subsequent requests.

  1. Click on the DEVICES tab and find the Copy App Link button located near the top-left corner of the screen. Click it to save the "Product Endpoint" to your clipboard. At this point in the tutorial, there should be no devices listed.


    NOTE: The Product Endopint can also be retrieved using the murano command line tool Example:

    murano domain --type product --brief

    Once the <product-endpoint> is determined, provisioning the device is typically done by the device firmware/software, but can be done with a tool such as curl for development purposes. Use the example command, below, for do provision a device and retrieve its authentication token.

    curl \
     -X POST 'https://<product-endpoint>/provision/activate' \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -d 'sn=<identity>'

    The device's authentication token <device-token> is contained in the body of the response.

    NOTE: If you see a response like HTTP/1.1 415 Unsupported Media Type, this likely means you have forgotten to enable Token Authentication and Murano is expecting you to use TLS Client Certificate authentication.

  2. Confirm that the device is now displayed with a provisioned status icon.


  3. Click on the LOGS tab. There you can see the provision event for this device. The LOGS page provides a "live" view that displays events associated with this product's API host that came in while the Murano product UI was running.


  4. Perform a device-write using the <device-token> obtained from the provision command and confirm that HTTP/1.1 204 No Content is returned from that call. The device token goes in the X-Exosite-CIK header.

    curl -i \
     -X POST 'https://<product-endpoint>/onep:v1/stack/alias' \
     -H 'X-Exosite-CIK: <device-token>' \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -d 'myalias=50'
  5. Verify the write was logged.


Note: Previous users of One Platform might be surprised to learn that the myalias resource does not need to be created before making the previous call in order for it to be logged. However, the data will not appear in the myalias resource unless it is defined in the RESOURCES tab of the Murano Product.

Provision a Device (TLS Client Certificate)

In the previous section, you provisioned a device using token authentication. Next, you may use TLS client certificate, which provides enhanced security:

- No secret information needs to be transmitted in order to authenticate requests.
- The private key can be stored on a hardware security chip that makes it difficult to obtain the key.
  1. Go to the SETTINGS tab and switch the product to use TLS Client Certificate. This does not affect already-provisioned devices, which retain their previous authentication type. Click the "SAVE" button at the bottom of that page.

    provisioning provisioning

  2. Find an identity that has not been provisioned yet. For this tutorial, you can use 00000002.


  3. Generate a certificate file. This will require a tool like OpenSSL. The CN of the certificate must be set to the device ID. For example, here is a command that generates a certificate good for 365 days:

     openssl req -x509 -nodes -days 365 -sha256 -subj /C=US/ST=MN/L=Mpls/O=Exosite/CN=00000002 -newkey rsa:2048 -keyout adc-key.pem -out adc-cert.pem
  4. -days 365 specifies that the certificate is valid for one year. The certificate also gets a start time based on the current time on the machine generating the certificate. This may differ by a few seconds from the API's clock and cause subsequent API calls to fail until the API's clock catches up to the start time of the certificate. You can check the API time by calling curl <product-endpoint>/timestamp, which returns a timestamp in seconds since the epoch.

  5. -subj /C=US/ST=MN/L=Mpls/O=Exosite/CN=00000002 specifies a specific location, organization, and identity. You should set most of this appropriately for your business, but Murano's device API requires that the common name /CN be set to your device identity.

  6. Combine the key and the cert into a single file using the cat command:

     cat adc-key.pem adc-cert.pem >> adc.pem
  7. Provision the device. This may be done by making an HTTP API call using the certificate created above. You will make a write call in this example. The provisioning step here is combined with the first write to the API. The steps differ somewhat based the operating system you are using.

In Linux, you can use the PEM file generated above directly:

curl -v "https://<product-endpoint>/onep:v1/stack/alias" -d 'myalias=55' -E ./adc.pem

In OSX, you should transform the PEM file into a PFX file and use that:

openssl pkcs12 -export -out adc.pfx -in adc.pem -password pass:guest
curl -v "https://<product-endpoint>/onep:v1/stack/alias" -d 'myalias=55' -E adc.pfx:guest

The first time you write with the certificate, you will see two events in the log: a provision event and a write event.


Here is a full example of certificate creation sequence and provisioning on an OSX machine:

$ openssl req -x509 -nodes -days 365 -sha256 -subj /C=US/ST=MN/L=Mpls/O=Exosite/CN=00000002 -newkey rsa:2048 -keyout adc-key.pem -out adc-cert.pem
Generating a 2048 bit RSA private key
writing new private key to 'adc-key.pem'
$ cat adc-key.pem adc-cert.pem >> adc.pem
$ openssl pkcs12 -export -out adc.pfx -in adc.pem -password pass:guest
$ curl -v -d 'myalias=55' -E adc.pfx:guest
*   Trying
* Connected to ( port 443 (#0)
* WARNING: SSL: Certificate type not set, assuming PKCS#12 format.
* Client certificate: 00000002
* TLS 1.2 connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate: *
* Server certificate: RapidSSL SHA256 CA
* Server certificate: GeoTrust Global CA
> POST /onep:v1/stack/alias HTTP/1.1
> Host:
> User-Agent: curl/7.51.0
> Accept: */*
> Content-Length: 10
> Content-Type: application/x-www-form-urlencoded
* upload completely sent off: 10 out of 10 bytes
< HTTP/1.1 204 No Content
< content-length: 0
< date: Wed, 03 May 2017 11:27:44 GMT
< server: Cowboy
* Curl_http_done: called premature == 0
* Connection #0 to host left intact