Provisioning with Amazon Cognito

By enabling Krypton for Amazon Cognito, you can easily request temporary credentials from a Cognito Identity Pool. Krypton implements the Enhanced Authflow Identity Pool Authentication Flow detailed in the Amazon Cognito Developer Guide documentation.

Enhanced Authflow

Krypton uses SIM authentication to call Amazon Cognito's GetOpenIdTokenForDeveloperIdentity API to receive an OpenID token. Krypton then uses the token with the GetCredentialsForIdentity API in order to request temporary AWS credentials.

After temporary credentials have been issued, your device will be able to securely access AWS services such as Amazon S3, without having to install credentials on the device beforehand. Moreover, credentials issued by Cognito through Krypton are valid for any network connection, allowing you to utilize ethernet or Wifi as a primary backhaul, and utilize the Soracom Air cellular connection as a backup.


Configuring Amazon Cognito

In order to enable Amazon Cognito integration, your AWS account must be configured to provide Krypton with programmatic access to Amazon Cognito. This process only needs to be performed once, and involves the following steps:

  1. Create and configure an Amazon Cognito Identity Pool.
  2. Create an IAM User with access for issuing OpenID tokens, and generate an Access key ID and Secret access key credential set.
  3. Register the credential set on Soracom, and configure Krypton.

Creating a Cognito Identity Pool

  1. Login to the AWS Management Console . From the Services menu, open the Cognito dashboard.

    https://console.aws.amazon.com

    Missing

  2. Click the Manage Identity Pools button.

    https://console.aws.amazon.com

    Missing

  3. Click the Create new identity pool button.

    https://console.aws.amazon.com

    Missing

  4. Enter an Identity pool name. Then set a Custom Authentication provider, and set the Developer provider name as krypton.soracom.io.

    https://console.aws.amazon.com

    Missing

  5. Click the Create Pool button.

  6. Cognito will give you the option of choosing which policies are applied to a device when it successfully authenticates using the identity pool. By default, Cognito will create new IAM roles to use with the identity pool, however you can specify a different role, or edit the role later if needed.

    Click the Allow button to finish creating the identity pool.

Once the identity pool has been created, Amazon Cognito will display its details. Make a note of the Identity pool ID, as it is required when configuring Krypton.

https://console.aws.amazon.com

Missing


Creating an IAM User

  1. From the AWS Services menu, open the IAM dashboard.

    https://console.aws.amazon.com

    Missing

  2. Click the Users section, then click the Add user button.

    https://console.aws.amazon.com

    Missing

  3. Enter a User name, and enable Programmatic access. Then click the Next: Permissions button.

    https://console.aws.amazon.com

    Missing

Our IAM user reqiures permission in order to utilize Cognito. This permission is provided by an AWS policy, which we will attach to our user:

  1. Under the Set permission section, click Attach existing policies directly.

  2. Search for the AmazonCognitoDeveloperAuthenticatedIdentities policy and click its to attach it to the new user.

    https://console.aws.amazon.com

    Missing

  3. Continue the Add user wizard by clicking the Next buttons, keeping the default values for the remaining sections. Then click Create user to complete the wizard.

    https://console.aws.amazon.com

    Missing

Once the new user has been created, it will appear along with its Access key ID and Secret access key. Save these keys in a secure location.

https://console.aws.amazon.com

Missing


Configuring Krypton

Once your AWS account has been configured using the above steps, you will have the following information:

You can then use this information to configure Krypton using the Krypton Configuration documentation, following the instructions for integrating Krypton with Amazon Cognito.

Once Krypton has been configured, your devices can begin using Krypton's provisioning service.


Example Provisioning Process

The following NodeJS project demonstrates the typical bootstrap process utilizing Krypton to request temporary credentials from Amazon Cognito in order to access Amazon S3.

Requirements:

Project Installation

Download the Krypton Example Project for NodeJS to your device and extract it. This will create a /kryptonExamples directory containing an cognito-auth.js NodeJS project file.

Open the /kryptonExamples directory and install package dependencies:

npm install

Authentication Method

The cognito-auth.js file expects a krypton-cognito script which will perform device authentication. Our example project includes the following authentication scripts:

Let's make a symlink for one of these scripts:

ln -sf krypton-cognito-cellular krypton-cognito

If using Air authentication, ensure that your modem is connected.

If using Endorse authentication, you will also need to download and extract the corresponding Krypton Client to the same /kryptonExamples directory. Refer to the Krypton Overview documentation and Krypton Client repositories for installation requirements and instructions.


Bootstrap

Now let's run the cognito-auth.js script:

node cognito-auth.js

As the script runs, it will perform the following:

Once the device has received credentials from Amazon Cognito, the NodeJS script will output Successfully obtained AWS credentials. You can also verify that the subscriber IMSI appears in in the Cognito identity pool by using the Amazon Cognito Identity Browser.

https://console.aws.amazon.com

Missing


Accessing AWS Resources

The cognito-auth.js script can be quickly modified to begin accessing AWS resources using the temporary credentials provided through Soracom Krypton and Amazon Cognito.

For example, to access the list of objects in an S3 bucket in your AWS account, edit the cognito-auth.js script to enable the following section:

initializeCredentials().then(() => {
  console.log("Successfully obtained AWS credentials");

  const s3 = new AWS.S3();

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

Make sure to replace my-s3-bucket with the name of your bucket. The IAM role attached to the device must also have the appropriate AWS policy for accessing S3 resources. Then simply re-run the script from your device to test that your device can successfully retrieve the list of objects.