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 token-based authentication, password authentication or TLS client certificates.

Requirements

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.

    provisioning

  2. Click Settings.

    provisioning

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

    provisioning

    provisioning

  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.

    provisioning

  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".

    provisioning

  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.

    provisioning

  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.

    (NOTE: 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
00000001,
00000002,
00000003,
00000004,
00000005,

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".

    provisioning

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

    provisioning

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:

    ID
    00000001
    00000002
    00000003
    00000004
    00000005
    

    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 or Password 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. After Provisioning, devices will have to use the provisioned credentials in all subsequent HTTP Data API methods (e.g. read, write, record, etc.)

NOTE: This step is only necessary for products that use Token or Password authentication. For TLS Client Certificate, please see that section below.

  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.

    provisioning

    NOTE: The Product Endpoint can also be retrieved using the murano command line tool.

    Example:

    $ murano domain --type product --brief
    
  2. 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. The example command as below.

    Token Authentication:

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

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

    Password Authentication:

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

    It will get HTTP/1.1 204 No Content.

    NOTE: If you see a response like HTTP/1.1 415 Unsupported Media Type, this likely means you have forgotten to enable Token or Password Authentication and Murano is expecting you to use TLS Client Certificate authentication. Or, the password you provided was less than 20 bytes in length.

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

    provisioning

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

    provisioning

  5. Perform a device-write using the token or password to confirm that HTTP/1.1 204 No Content is returned from that call.

    Token Authentication: 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'
    

    Password Authentication: The device credentials (base64-encoding of identity:password) in the Authorization header.

    $ curl -i -X POST 'https://<product-endpoint>/onep:v1/stack/alias' \
     -H 'Authorization: Basic <base64-encoding of identity:password>' \
     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
     -d 'myalias=50'
    
  6. Verify the write was logged.

    provisioning

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.

    provisioning

  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. 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.

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

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

provisioning

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'
-----
$ curl -v https://p5i31319yj6h6w29.m2.exosite.io/onep:v1/stack/alias -d 'myalias=55' --cert adc-cert.pem --key adc-key.pem
*   Trying 52.9.81.106...
* TCP_NODELAY set
* Connected to p5i31319yj6h6w29.m2.exosite.io (52.9.81.106) 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: *.m2.exosite.io
* Server certificate: RapidSSL SHA256 CA
* Server certificate: GeoTrust Global CA
> POST /onep:v1/stack/alias HTTP/1.1
> Host: p5i31319yj6h6w29.m2.exosite.io
> 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: Murano
<
* Curl_http_done: called premature == 0
* Connection #0 to host p5i31319yj6h6w29.m2.exosite.io left intact