Skip to content

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:

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

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

connector list

2.Click Settings.

3.For now, retain the default authentication method (token based). Next, scroll down to the Provisioning section.

provisioning & http

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

provisioning blank

- 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 Connector 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 West Connectivity 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 specific set of IP addresses.

save btn

7.Click SAVE. 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 User-Interface:

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

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.

Add Device popup

Enter an id for the device. Eg. 00000001.

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

On West Connectivity Connector User-Interface:

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

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

Add many devices

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

Upload CSV Many devices

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

ON the Connector page, click on the Devices tab and find the copy app link button located on the right side of the CONNECTOR-URL. Click it to save the 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.

copy domain

Provision with Token or Password

Provisioning a device with the "Allow devices to register their own identity" 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.)

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

2.Confirm that the device is now displayed.

device connected

3.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 connector's API host that came in while the Connector UI was running.

logs activated

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

5.Verify the write was logged.

Log Wrote

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.

Log Wrote

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.connect.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.connect.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.connect.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.connect.westpharma.com" matched cert's "*.m2.connect.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.connect.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.connect.westpharma.com left intact

PKI

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