Soracom Beam

Header Manipulation

When Soracom Beam fowards connections from an Air device to your endpoint, you can optionally enable header manipulation in order to add device information to the connection requests.

For example, a device may be configured to only send raw sensor data to Beam. Once Beam receives the data, it can add additional information to the data transmission (such as the SIM IMSI or device IMEI number), allowing your server to identify the source of the data or verify authorization. This lets you reduce cellular data usage by removing the need of including a device ID to the initial payload, and also removes the need of storing pre-shared keys directly on each device.

The types of header manipulations available vary based on the type of device (cellular, Sigfox, or LoRaWAN) and destination protocol (HTTP/HTTPS, TCP/TCPS, or MQTT/MQTTS).

Additional Header Options

Beam's header manipulation feature now also supports MSISDN and SIM ID values.

Device Type HTTP/HTTPS TCP/TCPS MQTT/MQTTS
Air for Cellular IMEI
IMSI
MSISDN
SIM ID
Signature
Custom		 IMEI
IMSI
MSISDN
SIM ID
Signature		 IMSI
Air for Sigfox
Air for LoRaWAN		 Operator ID
Device ID
Signature
Custom		 - -

Header Manipulation Options

IMEI Header

Air for Cellular only

Adds the device IMEI to the request header or packet data.

IMSI Header

Air for Cellular only

Adds the SIM card IMSI to the request header, packet data, or message topic.

MSISDN Header

Air for Cellular only

Adds the SIM card MSISDN to the header or packet data.

SIM ID Header

Air for Cellular only

Adds the SIM ID to the header or packet data. Useful if your SIM contains multiple Subscription Containers and you want to identify the incoming request by SIM rather than by its individual IMSIs.

Device ID Header

Air for Sigfox and Air for LoRaWAN only

Appends x-soracom-lora-device-id: {DEVICE-ID} or x-soracom-sigfox-device-id: {DEVICE-ID} to the HTTP/HTTPS request header.

Signature Header

All Air devices

Adds a SHA-256 signature to the header for authenticating the validity of the request against a pre-shared key. Because headers are added by Beam in the cloud, the device itself does not need to perform SHA-256 calculations (save energy), append additional headers (reduce data usage), or store pre-shared keys (improve security).

Usage with Air for Cellular devices

Enabling the Signature option requires one or more of the IMEI Header, IMSI Header, MSISDN Header, or SIM ID Header options to be enabled, and will append SHA-256 signature, signature version, and timestamp data to the request header or packet data. A pre-shared key must also be selected.

When selecting HTTP/HTTPS as the destination protocol, the following headers are appended to the request:

On your server application, you can then combine the header data using the following format, and calculate the SHA-256 value to verify that it matches the value in the x-soracom-signature header:

SHA256("{pre-shared key}x-soracom-imei={IMEI}x-soracom-imsi={IMSI}x-soracom-msisdn={MSISDN}x-soracom-sim-id={SIM-ID}x-soracom-timestamp={timestamp}")

Note that the header: value format in the HTTP request header is replaced with a header=value format, and that each header, including the pre-shared key and timestamp, should be concatenated without spaces in between.

Additionally, as the HTTP request headers may arrive in a different order, your server application should always concatenate these headers in the following order:

  • Pre-shared key
  • IMEI
  • IMSI
  • MSISDN
  • SIM ID
  • Timestamp

Depending on which header manipulations you have enabled, some headers may not be appended to the HTTP/HTTPS request. If you have not enabled certain header manipulation options, simply omit them from the concatenated string when calculating the SHA-256 signature value.

When selecting TCP/TCPS as the destination protocol, the following data is added to the packet data as the first line:

On your server application, you can simply combine your pre-shared key with the header manipulation values before the semicolon ;, and calculate the SHA-256 value to verify that it matches the value in the signature data:

SHA256("{pre-shared key}imei={IMEI} imsi={IMSI} msisdn={MSISDN} simId={SIM-ID} timestamp={timestamp}")

For information on how to use the Signature header to verify incoming data, refer to the Signature Verification documentation.

Note: If you are forwarding data using MQTT/MQTTS to a cloud-based MQTT broker (such as Azure IoT Hub, Google IoT Core, PubNub, or other broker), authentication is performed using MQTT authentication and credential sets rather than pre-shared keys. Refer to MQTT Entry Point configuration for further information.

Usage with Air for Sigfox and Air for LoRaWAN devices

Enabling the Signature option requires the Device ID option to be enabled, and will append a timestamp header to the request. A pre-shared key must also be selected.

The HTTP/HTTPS request will contain the following headers:

Once you receive the connection request on your endpoint server, you can verify the SHA-256 signature by combining the header information and pre-shared key:

SHA256("{pre-shared key}x-soracom-lora-device-id={DEVICE-ID}x-soracom-timestamp={timestamp}")
# or
SHA256("{pre-shared key}x-soracom-sigfox-device-id={DEVICE-ID}x-soracom-timestamp={timestamp}")

Custom Headers

All Air devices

Appends, replaces, or deletes headers from HTTP/HTTPS requests. Headers will be added, replaced, or removed based on the rules set before being forwarded to your destination endpoint.

Authorization Header

HTTP or Website entry points only

Adds an Authorization header to the HTTP request. There are 4 types in this header. Also see Credential Sets to understand credential sets.

Type Description
Bearer JWT Add an Authorization: Bearer {token} header to use the Bearer scheme defined in RFC 6750. In {token}, a JSON Web Token (JWT) issued using "Google Service Account (JSON)" credential set or "Private Key (PEM)" credential set will be inserted.
AWS Signature V4 Add AWS Signature Version 4. AWS Signature version 4 is generated using "AWS credentials" credential set or "AWS IAM Role credentials" credential set.
Bearer Add an Authorization: Bearer {token} header to use the Bearer scheme defined in RFC 6750. In {token}, "API Token credentials" or "Pre-Shared Key" credential set will be inserted.
Basic Add an Authorization: Basic {credentials} header to use Basic authentication as defined in RFC 7617. In {credentials}, a Base64 string generated from the user name and password set in "Username password credentials" credential set is inserted.