Device Provisioning

In this tutorial, you will create a West Connectivity Connector and demonstrate how to whitelist and provision devices. The tutorial covers the West Connectivity 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.

Note

this guide uses the HTTP Device APIs and we invite you to look the reference page along with this one.

Requirements

Before going further you should have:

A West Connectivity Business Account
A new Connector created from a blank template
The CURL tool to be installed on your computer

Notational Conventions

This document uses the following notational conventions:

A name in angle brackets (e.g., <myvar>) is a placeholder that will be defined elsewhere.

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 West Connectivity Connector. Provisioning devices of a given Connector 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 connectivity Settings, devices may or may not need to be whitelisted.

Encoding

For all requests examples as of Content-Type: application/x-www-form-urlencoded Non-alphanumeric characters from both part of the equal sign must be percent encoded as defined by the standard https://www.w3.org/TR/html401/interact/forms.html.

Configure Device Identity Format

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

A device identity uniquely identifies each device of a given Connector. 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.).

Navigate to your Connector solution's List and click the Connector name you created for this tutorial.
Click Settings from connector's menu.
Ensure that Self-Provisioning is disabled

This option specifies that device identities either do, or do not need to be whitelisted in the Connector before they connect. Leaving this option disabled means we will prescriptively define which device identities are allowed to connect, authenticate and communicate. If this option was enabled, devices will be provisioned with the identity that they present to West Connectivity when connecting for the first time.

Configure the chosen identity format for the Connector. 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).
Click SAVE button. You have now configured the provisioning settings for your Connector. 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

On West Connectivity Connector Web User-Interface:

Click the Devices tab and then click CREATE DEVICE(S) button and select One device.
Input a device identity adhering to your selected Identity Format from the previous step. In this tutorial, we're assuming a Base 10 format with a length of 8(Eg. 00000001.). Ensure the entered identity matches this format. Also note, an automatic 48-hour activation period is set by default, implying the device needs provisioning within 48 hours of its whitelisting.
Click CREATE to create the device. You will see the device listed in a whitelisted status on the device's page.

Whitelist Devices In Bulk

On West Connectivity Connector User-Interface:

You may whitelist several devices at once. Create a text file called identities.csv with the following content:

ID,TLS Client Certificate,Tags
00000001,,"[{""name"": ""group"", ""value"": ""g1""},{""name"": ""claim_code"", ""value"": ""abc""}]"
00000002,,"[{""name"": ""group"", ""value"": ""g1""},{""name"": ""claim_code"", ""value"": ""abc""}]"
00000003,,"[{""name"": ""group"", ""value"": ""g2""},{""name"": ""claim_code"", ""value"": ""def""}]"
00000004,,"[{""name"": ""group"", ""value"": ""g2""},{""name"": ""claim_code"", ""value"": ""def""}]"
00000005,,"[{""name"": ""group"", ""value"": ""g3""},{""name"": ""claim_code"", ""value"": ""def""}]"

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

Click the Devices tab and then click CREATE DEVICE(S) button and select Many devices.
Click UPLOAD CSV, navigate to the identities.csv file, and click CREATE. Now additional devices are whitelisted.

Provisioning Devices

After whitelisting your devices, you can provision them via the Connectivity Platform APIs within the provisioning restriction period that was originally set when the devices were created.

ON the Connector page, click the button on the right side of the Connector URL to save the Connector URL to your clipboard, You can also save the Connector ID to your clipboard by clicking the icon located on the right side of the ID.

Provision with Token or Password

Provisioning a device with the "Self-Provisioning" Connector configuration setting enabled means that your device will appear in the Devices tab of the Connector page 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.)

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://<CONNECTOR-DOMAIN>/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://<CONNECTOR-DOMAIN>/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 West Connectivity is expecting you to use TLS Client Certificate authentication. Or, the password you provided was less than 20 bytes in length.

Ensure that the device is now appearing without the 'Not Auth' status on Web UI.
Click on the Logs tab on Web UI. There you can see the provision event for this device. The Logs tab provides a "live" view that displays events associated with this connector's API host that came in while the Connector UI was running.
Perform a device-write using the token or password and confirm that a 204 No Content is returned from the call.

Token Authentication: The device token goes in the Authorization: Token header.

$ curl -i -X POST 'https://<CONNECTOR-DOMAIN>/api:v1/stack/alias' \
  -H 'Authorization: Token <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://<CONNECTOR-DOMAIN>/api: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'

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

Provision with 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 provisioning authentication to use TLS Client Certificate authentication. This does not affect already-provisioned devices, which retain their previous authentication type. Click the SAVE button at the bottom of that page.

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=West/CN=00000002 -newkey rsa:2048 -keyout device-key.pem -out device-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 https://<CONNECTOR-DOMAIN>/timestamp, which returns a timestamp in seconds since the epoch.

5.-subj /C=US/ST=MN/L=Mpls/O=West/CN=00000002 specifies a specific location, organization, and identity. You should set most of this appropriately for your business, but West Connectivity'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://<CONNECTOR-DOMAIN>/api:v1/stack/alias" -d 'myalias=55' --cert device-cert.pem --key device-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.

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=West/CN=00000002 -newkey rsa:2048 -keyout device-key.pem -out device-cert.pem
Generating a RSA private key
.............+++++
............+++++
writing new private key to 'device-key.pem'
-----
$ curl -v "https://<CONNECTOR-ID>.m2.diagnostic.westpharma.com/api:v1/stack/alias" -d 'myalias=55' --cert device-cert.pem --key device-key.pem
*   Trying 52.170.168.45:443...
* TCP_NODELAY set
* Connected to <CONNECTOR-ID>.m2.diagnostic.westpharma.com (88.88.88.88) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/certs/ca-certificates.crt
  CApath: /etc/ssl/certs
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* TLSv1.3 (IN), TLS handshake, Encrypted Extensions (8):
* TLSv1.3 (IN), TLS handshake, Request CERT (13):
* TLSv1.3 (IN), TLS handshake, Certificate (11):
* TLSv1.3 (IN), TLS handshake, CERT verify (15):
* TLSv1.3 (IN), TLS handshake, Finished (20):
* TLSv1.3 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.3 (OUT), TLS handshake, Certificate (11):
* TLSv1.3 (OUT), TLS handshake, CERT verify (15):
* TLSv1.3 (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use http/1.1
* Server certificate:
*  subject: CN=*.m2.diagnostic.westpharma.com
*  start date: Feb 27 16:27:35 2024 GMT
*  expire date: May 27 16:27:34 2024 GMT
*  subjectAltName: host "<CONNECTOR-ID>.m2.diagnostic.westpharma.com" matched cert's "*.m2.diagnostic.westpharma.com"
*  issuer: C=US; O=Let's Encrypt; CN=R3
*  SSL certificate verify ok.
> POST /api:v1/stack/alias HTTP/1.1
> Host: <CONNECTOR-ID>.m2.diagnostic.westpharma.com
> User-Agent: curl/7.68.0
> Accept: */*
> Content-Length: 10
> Content-Type: application/x-www-form-urlencoded
>
* upload completely sent off: 10 out of 10 bytes
* Mark bundle as not supporting multiuse
< HTTP/1.1 204 No Content
< date: Wed, 06 Mar 2024 08:29:39 GMT
< server: Platform
<
* Connection #0 to host <CONNECTOR-ID>.m2.diagnostic.westpharma.com left intact

PKI

Click here to refer how a custom Certificate Authority (CA) can be used to securely connect devices.