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:

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:

Types

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

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 200 Credential Sets.

If your application requires registering more than 200 Credential Sets to your Soracom account, please contact us 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:

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

    https://console.soracom.io

    Security

  2. From the Security screen, click the Credentials tab. Then click the Register a credentials set button.

    https://console.soracom.io

    Credentials

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

    Register Credentials

    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:

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

    https://console.soracom.io

    Security

  2. From the Security screen, click the Credentials tab.

  3. Find the Credential Set you want to delete, and click the icon next to it.

    https://console.soracom.io

    Delete Credentials


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:

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>

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:

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

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