SORACOM Developers

Documents

Details on group configuration

Introduction

Management of the settings for the various service functions of SORACOM is carried out by means of Groups. For each Group, configuration data is retained, and the individual services operate on the basis of this data.

Configuration structure

The configuration of a Group is as follows:

{
  "configuration":{
    "NAMESPACE":{
      "KEY1": "VALUE1",
      "KEY2": [ "VALUE2-1", "VALUE2-2" ],
      "KEY3": { "SUBKEY": "SUBVALUE" }
    }
  }
}

As seen here, the structure consists of multiple keys and values under each service (i.e., Namespace). Also, the values under the keys can be structured in a number of different ways. The configuration items for the individual services (Namespaces) will be described in detail later.

Updating a configuration

A configuration can be updated by executing — in an Update Group Configuration Parameters” API call — a PUT of the data in a format such as the one given below. (Note that if the same key already exists then it will be overwritten, but if the key is new then it will be appended.)

PUT /groups/{group_id}/configuration/{namespace}

The body section of the data that is PUT

[
  {
    "key": "KEY1",
    "value": "VALUE1"
  },
  {
    "key": "KEY2",
    "value": [ "VALUE2-1", "VALUE2-2" ]
  },
  {
    "key": "KEY3",
    "value": { "SUBKEY": "SUBVALUE" }
  }
]

In CLI, for example, updating can be carried out as below:

$ soracom group update_configuration --group-id GROUP-ID  \
  --namespace NAMESPACE \
  --params '[{"key":"KEY1","value":"VALUE1"},{"key":"KEY2","value":["VALUE2-1","VALUE2-2"]},{"key":"KEY3","value":{"SUBKEY":"SUBVALUE"}}]'

Next, the configuration items for the individual services (Namespaces) will be explained one function at a time.


Namespace: SoracomAir

SORACOM Air is a service that provides the “Air SIM” data communication SIM for use in IoT. Under this Namespace, the configuration that can be carried out mainly regards communications and the SIM.

Custom DNS function

This function provides a customized DNS server address when a Subscriber in this Group initiates communications. (See:Setting a Custom DNS)

※Please be aware that enabling this incurs additional costs.

Config parameters


"SoracomAir":{
   "useCustomDns": true | false, // Turns the function itself on or off; default is “false”
   "dnsServers": [ "DNS server IP address1", "DNS server IP address2" ] //  Maximum of 2
}

Sample request

[
  {
    "key": "useCustomDns",
    "value": true
  },
  {
    "key": "dnsServers",
    "value": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  }
]

Metadata service

From devices that are carrying out communications using SORACOM Air, this service permits information on the Subscriber that one is using to be obtained without authorization, permits user data configured in the Group to be obtained, etc. (See: Using the SORACOM Air metadata service function)

Config parameters

"SoracomAir": {
    "metadata": {
      "enabled": true | false, // Turns the function itself on or off; default is “false”
      "readonly": true | false, // Forbidding of write access; default is “true”
      "allowOrigin": "string" // Specifying of URL to permit cross-domain access by CORS
    },
    "userdata": "string" // Optional user-defined data
}

Sample request

[
  {
    "key": "metadata",
    "value": {
      "enabled": true,
      "readonly": true,
      "allowOrigin": "http://some.example.com"
    }
  },
  {
    "key": "userdata",
    "value": "foobar"
  }
]

Namespace: SoracomBeam

The SORACOM Beam service makes it possible to offload to the cloud tasks such as the high-load processing of encryption and the configuring of access points for IoT devices. Under this Namespace it is possible to carry out configuration regarding data transfer.

HTTP entry point

This configures the transfer — via HTTP or HTTPS — of communications received via HTTP with a particular pass. It is suited for transfers to API end points.

Config parameters

"http://beam.soracom.io:8888/": { // Fixed
  "name": "string", // Optional name
  "destination": "https://example.com/path/to/resource", // URL of communication destination
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true, // Whether or not Subscriber information is to be provided as a header
  "customHeaders": { // Custom HTTP header
    "X-HEADER-NAME": { // Name of custom header
      "action": "replace" | "append" | "delete", // Can choose between replacing, appending, and deleting
      "headerKey": "X-HEADER-NAME",
      "headerValue": "VALUE" // What is to be configured in the header
    }
  },
  "addSignature": true | false, // Whether or not signature for verification is to be provided
  "psk": "string" // Pre-shared passphrase to be used when calculating the signature for verification
}

Sample configuration

[
  {
    "key": "http://beam.soracom.io:8888/",
    "value": {
      "name": "test",
      "destination": "https://beamtest.soracom.io/",
      "enabled": true,
      "addSubscriberHeader": true,
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "replace",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "addSignature": true,
      "psk": "topsecret"
    }
  }
]

Website entry point

This configures the transfer — via HTTP or HTTPS — of communications received via HTTP toward all passes. It is suited for transferring entire websites via Beam.

The configured port is 18080, and communication can also be carried out using http://beam.soracom.io:18080, but the configuration is such that communication can also be carried out towards http://beam.soracom.io (port no. 80).

Config parameters

"http://beam.soracom.io:18080": { // Fixed; slash not included
  "name": "string", // Optional name
  "destination": "https://example.com", // Configure as far as FQDN of communication destination
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true, //  Whether or not Subscriber information is to be provided as a header
  "customHeaders": { // Custom HTTP header
    "X-HEADER-NAME": { // Name of custom header
      "action": "replace" | "append" | "delete", // Can choose between replacing, appending, and deleting
      "headerKey": "X-HEADER-NAME",
      "headerValue": "VALUE" // What is to be configured in the header
    }
  },
  "addSignature": true | false, // Whether or not signature for verification is to be provided
  "psk": "string" // Pre-shared passphrase to be used when calculating the signature for verification
}

Sample configuration

[
  {
    "key": "http://beam.soracom.io:18080",
    "value": {
      "name": "test",
      "destination": "https://beamtest.soracom.io",
      "enabled": true,
      "addSubscriberHeader": true,
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "replace",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "addSignature": true,
      "psk": "topsecret"
    }
  }
]

MQTT endpoint

This configures the transfer — via MQTT or MQTTS — of communications received via MQTT.

Config parameters

"mqtt://beam.soracom.io:1883": { // Fixed
  "name": "string", // Optional name
  "destination": "mqtts://mqtt.example.com/topicname", // MQTT broker
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true | false, // Whether or not to add IMSI to topic
  "username": "USERNAME", // Username (optional)
  "password": "PASSWORD", // Password (optional)
  "useClientCert": true | false, // Whether or not to use TLS client certificate
  "clientCerts": { // Required in case the above was enabled
    "default": { // Currently only one certificate can be registered
      "key": "...", // Private key (PEM format)
      "cert": "...", // Certificate (PEM format)
      "ca": "...", // CA certificate (PEM format)
    }
  },
  "useCaCert": true | false, // Whether or not to use a custom CA certificate
  "caCert": "...", // CA certificate (PEM format)
  "usePubnub": true | false, // Set to True if the destination is PubNub (optional, false if not specified)
  "useAzureIoT": true | false, // Set to True if the destination is AzureIoT (optional, false if not specified)
  "useGoogleIoT": true | false // Set to True if the destination is GoogleIoT (optional, false if not specified)

}

Sample configuration

[
  {
    "key": "mqtt://beam.soracom.io:1883",
    "value": {
      "name": "AWS IoT",
      "destination": "mqtts://data.iot.ap-northeast-1.amazonaws.com:8883",
      "enabled": true,
      "addSubscriberHeader": false,
      "useClientCert": true,
      "clientCerts": {
        "default": {
          "key": "-----BEGIN RSA PRIVATE KEY-----\n...",
          "cert": "-----BEGIN CERTIFICATE-----\n...",
          "ca": "-----BEGIN CERTIFICATE-----\n..."
        }
      }
    }
  }
]

TCP→TCP/TCPS entry point

This configures whether optional TCP socket communications are transferred as-is or with TLS encryption.

Config parameters

"tcp://beam.soracom.io:8023": { // Fixed
  "name": "string", // Optional
  "destination": "tcps://secure.example.com:1234", // Specify host name and port of the communication destination
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true | false, // Whether Subscriber information is sent when communication begins
  "addSignature": true | false, // Whether or not signature for verification is to be provided
  "psk": "string" // Pre-shared passphrase to be used when calculating the signature for verification
}

Sample configuration

[
  {
    "key":"tcp://beam.soracom.io:8023",
    "value": {
      "name": "beamtest",
      "destination": "tcps://beamtest.soracom.io:1234",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "psk": "topsecret"
    }
  }
]

TCP→HTTP/HTTPS entry point

This function carries out a POST in JSON format, either in HTTP or HTTPS, of data received via TCP socket. Because there is a possibility that the data received may be in binary, after base64 encoding it takes on a form like the one below, and is sent via POST.

{
  "payload": "BASE64-encoded data"
}

Config parameters

"tcp://beam.soracom.io:23080": { // Fixed
  "name": "string", // Optional
  "destination": "tcps://secure.example.com:1234", // Specify host name and port of the communication destination
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true | false, // Whether Subscriber information is sent when communication begins
  "addSignature": true | false, // Whether or not signature for verification is to be provided
  "psk": "string", // Pre-shared passphrase to be used when calculating the signature for verification
  "customHeaders": { // Custom HTTP header
    "X-HEADER-NAME": { // Name of custom header
      "action": "append" // Only appending is possible
      "headerKey": "X-HEADER-NAME",
      "headerValue": "VALUE" // What is to be configured in the header
    }
  }
}

Sample configuration

[
  {
    "key":"tcp://beam.soracom.io:23080",
    "value": {
      "name": "telnet2https",
      "destination": "https://beamtest.soracom.io/",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "psk": "topsecret",
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      }
    }
  }
]

UDP→HTTP/HTTPS entry point

This function carries out a POST in JSON format, either in HTTP or HTTPS, of data received via UDP. Because there is a possibility that the data received may be in binary, after base64 encoding it takes on a form like the one below, and is sent via POST.

{
  "payload": "BASE64-encoded data"
}

Config parameters

"udp://beam.soracom.io:23080": { // Fixed
  "name": "string", // Optional
  "destination": "tcps://secure.example.com:1234", // Specify host name and port of the communication destination
  "enabled": true | false, // Whether endpoint is enabled or disabled
  "addSubscriberHeader": true | false, // Whether Subscriber information is sent when communication begins
  "addSignature": true | false, // Whether or not signature for verification is to be provided
  "psk": "string", // Pre-shared passphrase to be used when calculating the signature for verification
  "customHeaders": { // Custom HTTP header
    "X-HEADER-NAME": { // Name of custom header
      "action": "append" // Only appending is possible
      "headerKey": "X-HEADER-NAME",
      "headerValue": "VALUE" // What is to be configured in the header
    }
  }
}

Sample configuration

[
  {
    "key":"udp://beam.soracom.io:23080",
    "value": {
      "name": "udp2https",
      "destination": "https://beamtest.soracom.io/",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSignature": true,
      "psk": "topsecret",
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      }
    }
  }
]

Namespace: SoracomEndorse

For devices that use an Air SIM, SORACOM Endorse provides device authentication service, with SORACOM serving as the authentication provider. Under this Namespace it is possible to carry out configuration of parameters to be included in tokens.

Config parameters

"SoracomEndorse": {
  "enabled": true | false,  // Turns the function itself on or off; default is “false”
  "parametersToEndorse" {  // Select parameters to be included in tokens. The parameters that can be selected are imsi, imei, msisdn, and requestParameters.
    "imsi": true | false,
    "imei": true | false,
    "msisdn": true | false,
    "requestParameters": true
  },
  "tokenTimeoutSeconds": 600, // (optional) Set the length of time (in seconds) that tokens will be valid from the time of issue
  "allowOrigin": "https://soracom.io",  //(optional) Configure this to enable CORS headers. The configured character string will be set as the access-control-allow-origin header for the response.
  "authorizedRedirectUrls": ["https://soracom.io", "http://localhost:3000"]  // (optional) When SORACOM Endorse’s response is used to redirect the client to a different URL, specifies candidate URLs for redirects. (Redirect requests to URLs not included in this parameter will be rejected.)
}

Sample configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key":"parametersToEndorse",
    "value": {
      "imsi": true,
      "imei": true,
      "msisdn": false,
      "requestParameters": true
    }
  },
  {
    "key": "tokenTimeoutSeconds",
    "value": 600
  },
  {
    "key": "allowOrigin",
    "value": "https://soracom.io"
  },
  {
    "key": "authorizedRedirectUrls",
    "value": ["https://soracom.io", "http://localhost:3000"]
  }
]

Namespace: SoracomFunnel

SORACOM Funnel is a cloud resource adapter that directly transfers data from devices to specified cloud services. Under this Namespace it is possible to configure the cloud service, resource URL, and credential information of transfer destinations.

Config parameters

"SoracomFunnel": {
  "enabled": true | fales // Turns the function itself on or off; default is “false”
  "destination": {
    "provider": "aws" | "azure" | "google", // Choose AWS,  Azure or Google
    "service": "aws-iot" | "kinesis" | "firehose" | "eventhubs" | "pubsub", // Choose AWS IoT, Kinesis Streams, Kinesis Firehose, Event Hubs or Google Cloud Pub/Sub
    "resourceUrl": "https://example.com/path/to/resource"  // Specify resource URL of cloud service
  },
  "credentialsId": "my-credentials",  // Name of credentials registered with SORACOM
  "contentType": "" | "json" // Specify processing to be applied to user data contained in payloads (In the case of JSON, parse as JSON)

Sample configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "destination",
    "value": {
      "provider": "aws",
      "service": "kinesis",
      "resourceUrl": "https://kinesis.ap-northeast-1.amazonaws.com/my-kinesis-stream"
    }
  },
  {
    "key": "credentialsId",
    "value": "my-credentials"
  },
  {
    "key": "contentType",
    "value": "json"
  }
]

Namespace: SoracomHarvest

SORACOM Harvest is a service that collects and accumulates data from IoT devices. Under this Namespace, set Harvest use on / off.

Config parameters

"SoracomHarvest": {
  "enabled": true | fales // Turns the function itself on or off; default is “false”
}

Sample configuration

[
  {
    "key": "enabled",
    "value": true
  }
]

Namespace: SoracomKrypton

SORACOM Krypton is a secure provisioning service. Under this Namespace, we will turn on / off use of Krypton and set up the provisioning API.

Amazon Cognito

Config parameters

"SoracomKrypton": {
  "enabled": true | fales, // Turns the function itself on or off; default is “false”
  "AmazonCognito": {
    "region": "us-xxx-xx", // The Cognito region to use.
    "credentialsId": "aws-xxx", //Specify the authentication information store name of Solacom.
    "identityPoolId": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx", //ID of Cognito's ID pool.
    "developerProviderName": "krypton.soracom.io" // Specify the developerProviderName set in Cognito.
  } 
}

Sample configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "AmazonCognito",
    "value": {
      "region": "us-west-2",
      "credentialsId": "aws-credential",
      "identityPoolId": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx",
      "developerProviderName": "krypton.soracom.io"
    } 
  }
]

AWS IoT

Config parameters

"SoracomKrypton": {
  "enabled": true | fales, // Turns the function itself on or off; default is “false”
  "AwsIot": {
    "region": "us-xxx-xx", //  The AWS IoT region to use.
    "credentialsId": "aws-xxx", //Specify the authentication information store name of Solacom.
    "policyName": "us-west-2:xxxxxxxx-xxxxx-xxxxxxx", //Enter the policy name to assign to the newly created certificate.
    "thingNamePattern": "myDevice-$imsi", // Enter the Thing name to use if the client does not specify it. If you specify `$ imsi`, IMSI replaces it as a placeholder.
    "host": "xxx.iot.us-west-2.amazonaws.com"
  } 
}

Sample configuration

[
  {
    "key": "enabled",
    "value": true
  },
  {
    "key": "AwsIot",
    "value": {
      "region": "us-west-2",
      "credentialsId": "aws-credential",
      "policyName": "myThingPolicy",
      "thingNamePattern": "myDevice-$imsi",
      "host": "xxx.iot.us-west-2.amazonaws.com"
     }
  }
]

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop