AWS authentication

When adding an Integration rule for an AWS endpoint such as for an AWS Lambda function rule, or a Firehose rule for AWS Kinesis or AWS SQS, there are two AWS authentication methods that can be used with Ably:

1. Credentials
2. ARN of an assumable role

These are a set of credentials for an AWS IAM user that has permission to invoke your Lambda function, and, in the case of a Firehose rule, publish to your AWS SQS queue or AWS Kinesis stream. These credentials consist of the ‘access key id’ and the ‘secret access key’ for the AWS IAM user. These are entered into the rule dialog as access_key_id:secret_access_key, that is, as a key-value pair, joined by a single colon (without a space). You can read more about these credentials in the AWS blog article How to quickly find and update your access keys, password, and MFA setting using the AWS Management Console.

This is not the recommended approach, as AWS best practices state that you should not share your access keys with third-parties.

When using this scheme you need to create a policy.

This scheme enables you to delegate access to resources on your account using an IAM role that the Ably AWS account can assume, avoiding the need to share user credentials with Ably. See this AWS blog article on roles.

This is the recommended scheme as it follows AWS best practices, and means you do not need to share your ‘access key id’ and the ‘secret access key’ with Ably, but instead specify the ARN of a role.

When using this scheme there are two steps you need to carry out:

1. Create a policy
2. Create a role

The following sections describe how to create a policy for the three main AWS services that Ably integrations supports:

1. AWS Lambda
2. AWS SQS
3. AWS Kinesis

The following steps show you how to create a policy for AWS Lambda.

1. In the IAM console sidebar select “Policies”:

1. Click “Create Policy”.

1. Click the JSON tab and enter the following JSON to configure the policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowInvokeLambdaFunction",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeAsync",
                "lambda:InvokeFunction"
            ],
            "Resource": [
                "arn:aws:lambda:<YOUR_AWS_REGION>:<YOUR_AWS_ACCOUNT>:function:<YOUR_FUNCTION_NAME>"
            ]
        }
    ]
}

Copy
Copied!

Note: You will need to replace <YOUR_AWS_REGION>, <YOUR_AWS_ACCOUNT>, and <YOUR_FUNCTION_NAME> with the AWS region that hosts your AWS Lambda function, your AWS account ID, and your AWS Lambda function name respectively.

1. Click “Next: Tags”. You don’t need to add any tags.

1. Click “Next: Review”.

1. Enter a suitable name for your policy:

1. Click “Create Policy”.

You have created a policy that grants the permissions required to invoke a Lambda function. You must now attach it to the role that you’ll specify in your Ably integration rule. The next step is to create the role.

The following steps show you how to create a policy for AWS SQS.

1. In the IAM console sidebar select “Policies”:

1. Click “Create Policy”.

1. Click the JSON tab and enter the following JSON to configure the policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowReadWriteSQS",
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:TagQueue",
                "sqs:GetQueueUrl",
                "sqs:ChangeMessageVisibility",
                "sqs:DeleteMessageBatch",
                "sqs:SendMessageBatch",
                "sqs:UntagQueue",
                "sqs:ReceiveMessage",
                "sqs:SendMessage",
                "sqs:ListQueueTags",
                "sqs:ChangeMessageVisibilityBatch"
            ],
            "Resource": [
                "arn:aws:sqs:<YOUR_AWS_REGION>:<YOUR_AWS_ACCOUNT>:<YOUR_QUEUE_NAME>"
            ]
        }
    ]
}

Copy
Copied!

Note: You will need to replace <YOUR_AWS_REGION>, <YOUR_AWS_ACCOUNT>, and <YOUR_QUEUE_NAME> with the AWS region that hosts your SQS queue, your AWS account ID, and your SQS queue name respectively.

1. Click “Next: Tags”. You don’t need to add any tags.

1. Click “Next: Review”.

1. Enter a suitable name for your policy.

1. Click “Create Policy”.

You have created a policy that grants the permissions required to use an SQS queue. You must now attach it to the role that you’ll specify in your Ably integration rule. The next step is to create the role.

The following steps show you how to create a policy for AWS Kinesis.

1. In the IAM console sidebar select “Policies”:

1. Click “Create Policy”.

1. Click the JSON tab and enter the following JSON to configure the policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ReadWriteToSingleStream",
            "Effect": "Allow",
            "Action": [
                "kinesis:DescribeLimits",
                "kinesis:DescribeStream",
                "kinesis:GetShardIterator",
                "kinesis:GetRecords",
                "kinesis:ListTagsForStream",
                "kinesis:MergeShards",
                "kinesis:PutRecord",
                "kinesis:PutRecords",
                "kinesis:UpdateShardCount"
            ],
            "Resource": [
                "arn:aws:kinesis:<YOUR_AWS_REGION>:<YOUR_AWS_ACCOUNT>:stream/<YOUR_STREAM_NAME>"
            ]
        }
    ]
}

Copy
Copied!

Note: You will need to replace <YOUR_AWS_REGION>, <YOUR_AWS_ACCOUNT> and <YOUR_STREAM_NAME> with the AWS region that hosts your Kinesis stream, your AWS account ID, and your Kinesis stream name respectively.

1. Click “Next: Tags”. You don’t need to add any tags.

1. Click “Next: Review”.

1. Enter a suitable name for your policy.

1. Click “Create Policy”.

You have created a policy that grants the permissions required to use a Kinesis stream. You must now attach it to the role that you’ll specify in your Ably integration rule. The next step is to create the role.

Create an IAM role as follows:

1. In the AWS IAM console, click “Roles” in the sidebar and then click the “Create Role” button:

1. For type of trusted entity select “Another AWS account”:

1. For Account ID specify 203461409171. This is the Ably AWS account.

1. Click the “Require external ID checkbox” and then enter an external ID of <Your_Ably_Account_ID>.<Your_Ably_app_ID>. This is also displayed when you create an Ably AWS Lambda, AWS Kinesis, or AWS SQS integration rule and select the “ARN of an assumable role” radio button in the create rule dialog. Learn more about finding your App ID here.

1. Click “Next: Permissions”.

1. Now select the policy you created earlier to attach to this role. You can type the name of your policy into the “Filter policies” search box:

Then ensure the checkbox for the policy is selected.

1. Click “Next: Tags”.

1. You don’t need to add tags so click “Next: Review”.

1. Enter a suitable name for your role.

1. Click “Create Role”.

When setting up an Ably integration rule, you can copy the ARN for your rule using the button provided:

When creating the Ably integration rule, enter the ARN of the rule created into the “Assume Role ARN“ text field of the rule creation dialog:

You can test your Ably rule by clicking “Test rule” in the Dashboard. If the test returns success you have the necessary AWS permissions in place and are correctly configured:

See the following resources for more information:

• AWS Best Practices
• IAM Identifiers
• IAM ARNs
• Webhooks
• Firehose