Credential Sets

For basic IoT applications, you may design your device to connect directly to your backend or cloud systems using the cellular connectivity provided by Soracom Air. To ensure security, you will typically need to install or preload authentication credentials directly onto your device so that it can authenticate directly with your backend systems.

As credential management can represent a significant portion of device management overhead (such as rotating or revoking credentials throughout the device lifecycle), you may find that managing credentials directly on each device presents certain logistical challenges, and you may instead want to leverage Soracom's platform services to reduce this overhead.

Credential Sets provides a secure authentication credential store within your Soracom account, which you can then use together with various Soracom services to allow the services to interact with your backend systems on behalf of your device.

Overview

Soracom provides several platform application services that allow you to integrate your IoT application with your backend system or various cloud services. For example:

Using Soracom Beam to connect to an MQTT broker (such as AWS IoT Core, Azure IoT Hub, or Google IoT) - The Beam service will proxy connections from your device to your broker.
Using Soracom Funnel to connect to a cloud provder (such as Amazon Kinesis, Azure Event Hubs, or Google Cloud Pub/Sub) - The Funnel service will forward data from your device to the cloud service provider.
Using Soracom Funk to connect to a cloud function (such as AWS Lambda, Azure Functions, or Google Cloud Functions) - The Funk service will call your cloud function when it receives data from your device.

In each case, your device interacts with the corresponding Soracom service directly. Since connections to Soracom are authenticated by SIM authentication, there is no need for your device to provide separate authentication credentials. In turn, you can configure each service to point to your service endpoint, and Soracom will add the necessary authentication credentials to the outgoing connections when it connects to those endpoints.

In order for Soracom to add authentication credentials on your device's behalf, you must register Credential Sets to your Soracom account, and specify in your Beam, Funnel, Funk, or other service configuration to use the corresponding credentials.

As Soracom platform service configuration is managed by Groups, the Credential Set that Soracom adds to outgoing connections depends on which group your SIM is assigned to, and which Credential Sets are configured in that group.

Moving the storage of credentials from your device to your Soracom account can drastically improve credential management overhead:

When using a shared authentication credential across multiple devices, you can register a single Credential Set and assign it to a group containing multiple SIMs. Credential rotation is drastically simplified since you can simply assign a new Credential Set in your group configuration, and all SIMs in the group will inherit the new credentials.
When moving devices across different environments (such as development, staging, and production), your devices do not need to manage multiple certificates. Instead, you can create separate groups that correspond to each individual environment, and assign Credential Sets accordingly. Then as you move a SIM from one group to another, the authentication credentials it uses is seamlessly updated.
When provisioning unique credentials for each device, you can programmatically register the credentials to your Soracom account directly, and configure your group to dynamically select which Credential Set should be used based on SIM parameters such as IMSI. In turn, these credentials do not need to be installed on the device at the factory, simplifying your manufacturing process.

Types

At this time, Soracom supports registration of the following types of credentials:

AWS credentials (AWS Access Key ID and AWS Secret Access Key)
AWS IAM Role credentials (Role ARN and External ID)
Azure credentials (Policy Name and Key)
Azure IoT credentials (Access Policy Name and Shared Access Key)
Google IoT credentials (Registry ID, Device ID, and Private Key)
Google Service Account (JSON credentials)
PubNub credentials (Publish Key and Subscribe Key)
X.509 certificate (Key, Certificate, and Root CA)
Pre-Shared Key

Access Control

Credential sets apply to your Soracom account, and can be managed by either your Root Account or by a SAM User with sufficient API permissions.

Each credential is encrypted at rest to ensure that credentials remain secure while stored in your Soracom account.

Limitations

Each Soracom account is limited to 100 Credential Sets.

If your application requires registering more than 100 Credential Sets to your Soracom account, please contact Soracom support to request a limit increase.

Compared to AuthKeys

A Credential Set is used by Soracom to programmatically interact with or perform actions on an external service or device on your behalf.

By comparison, an AuthKey is an authentication mechanism that allows an external application (such as a webhook on your backend system) to access your Soracom account and perform actions using the Soracom API or Soracom CLI.

Creating a Credential Set

To register a Credential Set to your Soracom account:

Login to the User Console. Click your account menu, then select Security.

https://console.soracom.io
From the Security screen, click the Credentials tab. Then click the Register a credentials set button.

https://console.soracom.io
In the Register a credentials set dialog, enter a unique Credentials set ID. You can optionally specify a Description. Then select the Type, and enter the credentials according to the type of credentials selected.

When entering multi-line credentials such as X.509 certificates, you may need to verify if your endpoint has any specific line ending requirements. In many cases, you may need to enter these credentials with a line feed or \n character, but without a carriage return or \r character.

Finally, click the Register button to store the credentials to your Soracom account.

When configuring Soracom services such as Beam, Funnel, and Funk, you can also register a new Credential Set directly from the service configuration screen. Refer to each service's configuration documentation for more information.

Your credential set can now be selected when configuring other Soracom services such as Soracom Beam, Funnel, and Funk.

Deleting a Credential Set

Before deleting a Credential Set, ensure that it is not currently used in any Soracom platform service configurations. If you delete a Credential Set that is still associated with a service configuration, this may cause unexpected errors such as lost data.

You can similarly delete a Credential Set from your account:

Login to the User Console. Click your account menu, then select Security.

https://console.soracom.io
From the Security screen, click the Credentials tab.
Find the Credential Set you want to delete, and click the icon next to it.

https://console.soracom.io

Programmatic Usage

You can use the Soracom API or Soracom CLI to programmatically manage Credential Sets in your Soracom account.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the createCredential API to register a new Credential Set:

Global
Japan

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "description": "",
>        "type": "psk",
>        "credentials": {
>          "key": "my-secret-key"
>        }
>      }' \
>  https://g.api.soracom.io/v1/credentials/<CREDENTIAL-ID>

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "description": "",
>        "type": "psk",
>        "credentials": {
>          "key": "my-secret-key"
>        }
>      }' \
>  https://jp.api.soracom.io/v1/credentials/<CREDENTIAL-ID>

The API will return a JSON response indicating that the credentials were successfully registered:

{
  "description": "",
  "type": "psk",
  "credentials": {},
  "credentialsId": "my-credentials",
  "createDateTime": 1614239275,
  "updateDateTime": 1614239275
}

For security, the credentials will never be returned directly, so the credentials parameter will normally contain an empty object.

For additional Credential Set management actions, use one of the following APIs:

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to register a new Credential Set:

Global
Japan

soracom credentials create --credentials-id <CREDENTIALS-ID> --body '{"description":"","type":"psk","credentials":{"key":"my-secret-key"}}' --coverage-type g

soracom credentials create --credentials-id <CREDENTIALS-ID> --body '{"description":"","type":"psk","credentials":{"key":"my-secret-key"}}' --coverage-type jp

The CLI will return a response similar to the API example above.

For additional Credential Set management actions, use one of the following CLI commands:

soracom credentials list
soracom credentials update
soracom credentials delete

Account Security

Credential Sets

Overview

Types

Access Control

Limitations

Compared to AuthKeys

Creating a Credential Set

Deleting a Credential Set

Programmatic Usage

Soracom API

Soracom CLI