Create a permissions policy Create an IAM role

Stream permissions in QLDB

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

Before creating an Amazon QLDB stream, you must provide QLDB with write permissions to your specified Amazon Kinesis Data Streams resource. If you're using a customer managed AWS KMS key for server-side encryption of your Kinesis stream, you must also provide QLDB with permissions to use your specified symmetric encryption key. Kinesis Data Streams doesn't support asymmetric KMS keys.

To provide your QLDB stream with the necessary permissions, you can make QLDB assume an IAM service role with the appropriate permissions policies. A service role is an IAM role that a service assumes to perform actions on your behalf. An IAM administrator can create, modify, and delete a service role from within IAM. For more information, see Create a role to delegate permissions to an AWS service in the IAM User Guide.

Note

To pass a role to QLDB when requesting a journal stream, you must have permissions to perform the iam:PassRole action on the IAM role resource. This is in addition to the qldb:StreamJournalToKinesis permission on the QLDB stream subresource.

To learn how to control access to QLDB using IAM, see How Amazon QLDB works with IAM. For a QLDB policy example, see Identity-based policy examples for Amazon QLDB.

In this example, you create a role that allows QLDB to write data records to a Kinesis data stream on your behalf. For more information, see Creating a role to delegate permissions to an AWS service in the IAM User Guide.

If you're streaming a QLDB journal in your AWS account for the first time, you must first create an IAM role with the appropriate policies by doing the following. Or, you can use the QLDB console to automatically create the role for you. Otherwise, you can choose a role that you previously created.

Create a permissions policy

Complete the following steps to create a permissions policy for a QLDB stream. This example shows a Kinesis Data Streams policy that grants QLDB permissions to write data records to your specified Kinesis data stream. If applicable, the example also shows a key policy that allows QLDB to use your symmetric encryption KMS key.

For more information about Kinesis Data Streams policies, see Controlling access to Amazon Kinesis Data Streams resources using IAM and Permissions to use user-generated KMS keys in the Amazon Kinesis Data Streams Developer Guide. To learn more about AWS KMS key policies, see Using key policies in AWS KMS in the AWS Key Management Service Developer Guide.

Note

Your Kinesis data stream and KMS key must both be in the same AWS Region and account as your QLDB ledger.

To use the JSON policy editor to create a policy

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation column on the left, choose Policies.

If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose Get Started.
At the top of the page, choose Create policy.
Choose the JSON tab.

Enter a JSON policy document.

If you're using a customer managed KMS key for server-side encryption of your Kinesis stream, use the following example policy document. To use this policy, replace us-east-1, 123456789012, kinesis-stream-name, and 1234abcd-12ab-34cd-56ef-1234567890ab in the example with your own information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QLDBStreamKinesisPermissions",
            "Action": [ "kinesis:PutRecord*", "kinesis:DescribeStream", "kinesis:ListShards" ],
            "Effect": "Allow",
            "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/kinesis-stream-name"
        },
        {
            "Sid": "QLDBStreamKMSPermission",
            "Action": [ "kms:GenerateDataKey" ],
            "Effect": "Allow",
            "Resource": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab"
        }
    ]
}

Otherwise, use the following example policy document. To use this policy, replace us-east-1, 123456789012, and kinesis-stream-name in the example with your own information.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QLDBStreamKinesisPermissions",
            "Action": [ "kinesis:PutRecord*", "kinesis:DescribeStream", "kinesis:ListShards" ],
            "Effect": "Allow",
            "Resource": "arn:aws:kinesis:us-east-1:123456789012:stream/kinesis-stream-name"
        }
    ]
}

Choose Review policy.

Note
You can switch between the Visual editor and JSON tabs any time. However, if you make changes or choose Review policy in the Visual editor tab, IAM might restructure your policy to optimize it for the visual editor. For more information, see Policy restructuring in the IAM User Guide.
On the Review policy page, enter a Name and an optional Description for the policy that you are creating. Review the policy Summary to see the permissions that are granted by your policy. Then choose Create policy to save your work.

Create an IAM role

After creating a permissions policy for your QLDB stream, you can then create an IAM role and attach your policy to it.

To create the service role for QLDB (IAM console)

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane of the IAM console, choose Roles, and then choose Create role.
For Trusted entity type, choose AWS service.
For Service or use case, choose QLDB, and then choose the QLDB use case.
Choose Next.
Select the box next to the policy that you created in the previous steps.
(Optional) Set a permissions boundary. This is an advanced feature that is available for service roles, but not service-linked roles.
1. Open the Set permissions boundary section, and then choose Use a permissions boundary to control the maximum role permissions.
  
  IAM includes a list of the AWS managed and customer-managed policies in your account.
2. Select the policy to use for the permissions boundary.
Choose Next.
Enter a role name or a role name suffix to help you identify the purpose of the role.
Important
When you name a role, note the following:
- Role names must be unique within your AWS account, and can't be made unique by case.
  
  For example, don't create roles named both PRODROLE and prodrole. When a role name is used in a policy or as part of an ARN, the role name is case sensitive, however when a role name appears to customers in the console, such as during the sign-in process, the role name is case insensitive.
- You can't edit the name of the role after it's created because other entities might reference the role.
(Optional) For Description, enter a description for the role.
(Optional) To edit the use cases and permissions for the role, in the Step 1: Select trusted entities or Step 2: Add permissions sections, choose Edit.
(Optional) To help identify, organize, or search for the role, add tags as key-value pairs. For more information about using tags in IAM, see Tags for AWS Identity and Access Management resources in the IAM User Guide.
Review the role, and then choose Create role.

The following JSON document is an example of a trust policy that allows QLDB to assume an IAM role with specific permissions attached to it.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "qldb.amazonaws.com"
            },
            "Action": [ "sts:AssumeRole" ],
            "Condition": {
                "ArnEquals": {
                    "aws:SourceArn": "arn:aws:qldb:us-east-1:123456789012:stream/myExampleLedger/*"
                },
                "StringEquals": {
                    "aws:SourceAccount": "123456789012"
                }
            }
        }
    ]
}

Note

This trust policy example shows how you can use the aws:SourceArn and aws:SourceAccount global condition context keys to prevent the confused deputy problem. With this trust policy, QLDB can assume the role for any QLDB stream in the account 123456789012 for the ledger myExampleLedger only.

For more information, see Cross-service confused deputy prevention.

After creating your IAM role, return to the QLDB console and refresh the Create QLDB stream page so that it can find your new role.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Stream records

Common errors