Trust Relationship Role

The AWS integrations are securely configured by means of a Trust Relationship of the BICS Datastreamer role (arn:aws:iam::884047677700:role/datastreamer). The Trust Relationship can be added to new and/or already-existing roles.

The following JSON shows an example policy document that should be added in the Trust Relationship.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "",
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::884047677700:role/datastreamer"
        ]
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "ForAnyValue:StringEquals": {
          "sts:ExternalId": [
            "org-1234"
          ]
        }
      }
    }
  ]
}

Note: The ExternalID must match with the BICS organisation number, so for an organisation with a numeric ID of 1234, the value above shows org-1234. The numeric ID of an organisation can be retrieved with a call to /organisation/my.

S3 AWS Configuration

This section covers the steps necessary to create a new role with S3 write access.

  1. In the AWS console, navigate to S3 and create a new bucket

  2. In IAM -> Policies click Create Policy to create a policy which allows PutObject permissions to the S3 bucket.

  3. In IAM -> Roles, click Create Role for the S3 use case and click Next: Permissions

  4. Attach the policy created in step 2 and click Next: Tags, then Create Role.

  5. Edit the newly-created role and click Trust Relationships -> Edit Trust Relationships

  6. Copy the policy document JSON listed above with your organisation ID in place to allow BICS’s datastreamer role write access.

The newly-created role ARN should be used in the API call as the api_username parameter as shown in the request body example.

NOTES:

Create S3 Data Stream

POST simforthings.bics.com/api/v1/data_stream:

{
  "stream_historic_data": 0,
  "data_stream_type": {
    "description": "Usage Data & Events",
    "id": 3
  },
  "api_type": {
    "description": "AWS S3",
    "id": 8
  },
  "api_username": "arn:aws:iam::<your-account_id>:role/<bucket-role-name>",
  "api_parameter": "eu-west-1/bucket-name"
}

Kinesis AWS Configuration

This section covers the steps necessary to create a new role with Kinesis write access.

  1. In the AWS console, navigate to Kinesis and create a new stream

  2. In IAM -> Policies click Create Policy which allows PutRecord and PutRecords write permissions to the Kinesis stream.

  3. In IAM -> Roles, click Create Role for Kinesis Analytics and click Next: Permissions

  4. Attach the policy created in step 2 and click Next: Tags -> Create Role.

  5. Edit the newly-created role and click Trust Relationships -> Edit Trust Relationships

  6. Copy the policy document JSON listed above with your organisation ID in place to allow BICS’s datastreamer role write access.

The newly-created role ARN should be used in the API call as the api_username parameter as shown in the request body example.

To create a data streamer for AWS services, a POST request should be sent to https://simforthings.bics.com/api/v1/data_stream.

Create Kinesis Data Stream

POST simforthings.bics.com/api/v1/data_stream:

{
  "stream_historic_data": 0,
  "data_stream_type": {
    "description": "Usage Data & Events",
    "id": 3
  },
  "api_type": {
    "description": "AWS Kinesis",
    "id": 4
  },
  "api_username": "arn:aws:iam::<your-account_id>:role/<kinesis-role-name>",
  "api_parameter": "eu-west-1/<kinesis-stream-name>"
}

Tip: eu-west-1/ will be used as a default region if only the kinesis-stream-name is configured

For more information, see the /data_stream Swagger Reference.