SORACOM Developers

Getting Started

Get Cognito credentials with Krypton and download files from S3

In this guide, we will use SIM authentication to acquire the credentials of SORACOM Krypton (Krypton) service for Amazon Cognito and download the file from S3.

Introduction

Krypton is a service that provides secure provisioning using SIM authentication platform on SIM and SORACOM cellular core network issued by SORACOM.

In Krypton there are two authentication methods for provisioning:

In this guide, do you authenticate using “SIM authentication with SORACOM Endorse” For the authentication method.

SORACOM Krypton supports Amazon Cognito developer authenticated identities authflow described on the following link. (To be more specific, it supports enhanced auth flow of developer authenticated identities auth flow.)

The user can use SORACOM Krypton as a developer provider in the following diagram, i.e. SORACOM Krypton authenticates a device by using SIM, calls GetOpenIdTokenForDeveloperIdentity API of Amazon Cognito and returns an open ID token so that the device can call GetCredentialsForIdentity to receive temporary AWS credentials.

In this section we configure SORACOM Krypton to implement the above auth flow so that a SIM authenticated client can obtain temporary AWS credentials with a user configured set of permissions. As a result of successful transaction, a client can access any AWS service by using the credentials according to the granted permission set.

Here are the steps.

  1. Create Amazon Cognito user identity pool and configure to use developer authenticated identities
  2. Create AWS IAM credentials that has permission to provide an open ID token to an authenticated client.
  3. Configure SORACOM Krypton
  4. Get temporary AWS credentials and access AWS resources

Once the above has finished, a device with SORACOM SIM and Krypton client can obtain temporary AWS credentials. The user has full control for the permission set given to an authenticated client.

The assumptions are as follows.

Create Amazon Cognito user identity pool and configure to use developer authenticated identities

Go to Amazon Cognito management console

Krypton-Cognito

Click on Manage Identity Pools

Krypton-Cognito

Click on Create new identity pool

Krypton-Cognito

Give a name to user pool, set developer provider name to krypton.soracom.io and click on Create Pool.

Krypton-Cognito

Name IAM role created for authenticated users in the pool. The policy document shown on the screen will be assigned to the client. Edit it appropriately here or you can also edit the policy document(s) assigned to the role later.

Copy and store the user identity pool ID as we will use it in SORACOM Krypton configuration

Krypton-Cognito

Create AWS IAM credentials that has permission to provide an open ID token to an authenticated client.

In order for SORACOM Krypton to access Amazon Cognito identity pool and generate credentials, a set of AWS credentials with a right permission set is required. This section walks you though the steps to create an AWS IAM user, attach a right set of policies and obtain a set of AWS credentials.

Go to AWS IAM management console

Krypton-Cognito

Go to Users section and client on Add user

Krypton-Cognito

Give a name to the user that we are going to create, allow programmatic access and click Next: Permissions

Krypton-Cognito

Select Attach existing policies directly, search AmazonCognitoDeveloperAuthenticatedIdentities policy and click on the checkbox.  

Krypton-Cognito

Review the configuration and click on Create User.

Krypton-Cognito

Copy both AWS access key ID and secret access key and paste them somewhere you can save the information securely. (Note that AWS secret access key is shown only once at this point. Make sure you have store them as we need to use the value later).

Krypton-Cognito

Configure SORACOM Krypton

By following the steps in the above, you have collected information you will need to configure SORACOM Krypton. Now we configure a configuration group so that a SIM can use the information to provision a thing in AWS IoT. We first create an entry in SORACOM credentials store and configure the credentials ID and AWS IoT related parameters to a configuration group.

Register AWS credentials to SORACOM credentials store

Go to SORACOM user console and select Security in the operator menu at the right top corner

Krypton-Cognito

Go to credentials section and click on Register a credentials set.

Krypton-Cognito

Give a name to the credentials set, select AWS credentials as the type, and copy and paste AWS credentials we created in the previous section.

Krypton-Cognito

Create a configuration group and put a SIM into the group

Go to groups menu on SORACOM user console

Krypton-Cognito

Create a group by clicking on Add button (or select a group if you are going to use existing one)

Click on the group and go into the configuration editor view.

Krypton-Cognito

Set Cognito information in the SIM group. Based on the contents set in “Step 1” and “Step 2”, set the group as follows

"region": "ap-northeast-1",
"credentialsId": "aws-xxx-krypton",
"identityPoolId": "ap-northeast-1:xxxxxxxxx",
"developerProviderName": "krypton.soracom.io"

Open the relevant SIM group and enter the information of Cognito. Please turn on Krypton.

Krypton-Cognito

Then select the SIM management menu.

Krypton-Cognito

Please select the SIM to use and click Change group on the Actions menu

Krypton-Cognito

Select the SIM group and click Update.

Krypton-Cognito

Get temporary AWS credentials and access AWS resources

Now you have finished configuring to use SORACOM Krypton to provide temporary AWS credentials to a SIM authenticated client. Let us now run an example script that authenticates by using SIM, obtains temporary AWS credentials. It periodically refreshes the credentials before it expires.

Download the sample project (nodejs) in the same folder and unpack it. Move to the folder “kryptonExamples” created after decompression and execute the following command.

$ npm install

Next, set up according to Krypton’s authentication method.

Authentication using SORACOM Air cellular line

When using SORACOM Air’s cellular line authentication, execute the following command.

$ ln -sf krypton-cognito-cellular krypton-cognito

SIM authentication with SORACOM Endorse

When using SIM authentication by SORACOM Endorse, first check the following preconditions.

Prerequisites:

If the prerequisite is satisfied, please download soracom-krypton.jar from soracom-krypton-client-for-java in the same folder as ‘kryptonExamples’. Then move to “kryptonExamples” and execute the following command.

$ ln -sf krypton-cognito-endorse krypton-cognito

The setup according to the authentication method is completed with the above.

Get temporary AWS credentials and access AWS resources

In case of authentication using Sorachom Air’s cellular line, please confirm that you can connect with Air SIM.

Run node cognito-auth.js

$ node cognito-auth.js

If you see a message saying “Successfully obtained AWS credentials“, you have successfully authenticated the device by using SORACOM Krypton. Now you should be able to see the IMSI on identity browser for the identity pool on Amazon Cognito console.

Krypton-Cognito

Access to S3

So far, you can change the sample script to access AWS resources such as Amazon S3 bucket and Kinesis Video Stream.

To access S3, open the script “cognito-auth.js” and edit the following part. Below is a list of bucket objects specified by S3.

initializeCredentials().then(() => {
  console.log("Successfully obtained AWS credentials");
  /* Here write code to access AWS resources, e.g.
    const s3 = new AWS.S3();

    s3.listObjects({Bucket: 'your-s3-bucket'}, (err, data) => {
      if (err) console.error(err);
      console.log(data);
    });
  */
});

You must configure AWS IAM roles associated with authenticated users together.

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