Controlling access to Amazon Kinesis Data Streams resources using IAM
Amazon Identity and Access Management (IAM) enables you to do the following:
-
Create users and groups under your Amazon account
-
Assign unique security credentials to each user under your Amazon account
-
Control each user's permissions to perform tasks using Amazon resources
-
Allow the users in another Amazon account to share your Amazon resources
-
Create roles for your Amazon account and define the users or services that can assume them
-
Use existing identities for your enterprise to grant permissions to perform tasks using Amazon resources
By using IAM with Kinesis Data Streams, you can control whether users in your organization can perform a task using specific Kinesis Data Streams API actions and whether they can use specific Amazon resources.
If you are developing an application using the Kinesis Client Library (KCL), your policy must include permissions for Amazon DynamoDB and Amazon CloudWatch; the KCL uses DynamoDB to track state information for the application, and CloudWatch to send KCL metrics to CloudWatch on your behalf. For more information about the KCL, see Develop KCL 1.x consumers.
For more information about IAM, see the following:
For more information about IAM and Amazon DynamoDB, see Using IAM to Control Access to Amazon DynamoDB Resources in the Amazon DynamoDB Developer Guide.
For more information about IAM and Amazon CloudWatch, see Controlling User Access to Your Amazon Account in the Amazon CloudWatch User Guide.
Contents
- Policy syntax
- Actions for Kinesis Data Streams
- Amazon Resource Names (ARNs) for Kinesis Data Streams
- Example policies for Kinesis Data Streams
- Share your data stream with another account
- Configure an Amazon Lambda function to read from Kinesis Data Streams in another account
- Share access using resource-based policies
Policy syntax
An IAM policy is a JSON document that consists of one or more statements. Each statement is structured as follows:
{
"Statement":[{
"Effect":"effect
",
"Action":"action
",
"Resource":"arn
",
"Condition":{
"condition
":{
"key
":"value
"
}
}
}
]
}
There are various elements that make up a statement:
-
Effect: The effect can be
Allow
orDeny
. By default, IAM users don't have permission to use resources and API actions, so all requests are denied. An explicit allow overrides the default. An explicit deny overrides any allows. -
Action: The action is the specific API action for which you are granting or denying permission.
-
Resource: The resource that's affected by the action. To specify a resource in the statement, you need to use its Amazon Resource Name (ARN).
-
Condition: Conditions are optional. They can be used to control when your policy will be in effect.
As you create and manage IAM policies, you might want to use the IAM Policy Generator and the IAM Policy Simulator.
Actions for Kinesis Data Streams
In an IAM policy statement, you can specify any API action from any service that
supports IAM. For Kinesis Data Streams, use the following prefix with the name of the API action:
kinesis:
. For example: kinesis:CreateStream
,
kinesis:ListStreams
, and kinesis:DescribeStreamSummary
.
To specify multiple actions in a single statement, separate them with commas as follows:
"Action": ["kinesis:action1", "kinesis:action2"]
You can also specify multiple actions using wildcards. For example, you can specify all actions whose name begins with the word "Get" as follows:
"Action": "kinesis:Get*"
To specify all Kinesis Data Streams operations, use the * wildcard as follows:
"Action": "kinesis:*"
For the complete list of Kinesis Data Streams API actions, see the Amazon Kinesis API Reference.
Amazon Resource Names (ARNs) for Kinesis Data Streams
Each IAM policy statement applies to the resources that you specify using their ARNs.
Use the following ARN resource format for Kinesis data streams:
arn:aws-cn:kinesis:region
:account-id
:stream/stream-name
For example:
"Resource": arn:aws-cn:kinesis:*:111122223333:stream/my-stream
Example policies for Kinesis Data Streams
The following example policies demonstrate how you could control user access to your Kinesis data streams.
Share your data stream with another account
Note
Kinesis Producer Library currently does not support specifying a stream ARN when writing to a data stream. Use the Amazon SDK if you want to write to a cross-account data stream.
Attach a resource-based policy to your data stream to grant access to another account, IAM user, or IAM role. Resource-based policies are JSON policy documents that you attach to a resource such as a data stream. These policies grant the specified principal permission to perform specific actions on that resource and define under what conditions this applies. A policy can have multiple statements. You must specify a principal in a resource-based policy. Principals can include accounts, users, roles, federated users, or Amazon services. You can configure policies in the Kinesis Data Streams console, API or SDK.
Note that sharing access to registered consumers such as Enhanced Fan Out requires a policy on both the data stream ARN and the consumer ARN.
Enable cross-account access
To enable cross-account access, you can specify an entire account or IAM entities in another account as the principal in a resource-based policy. Adding a cross-account principal to a resource-based policy is only half of establishing the trust relationship. When the principal and the resource are in separate Amazon accounts, you must also use an identity-based policy to grant the principal access to the resource. However, if a resource-based policy grants access to a principal in the same account, no additional identity-based policy is required.
For more information about using resource-based policies for cross-account access, see Cross account resource access in IAM.
Data stream administrators can use Amazon Identity and Access Management policies to specify who has access to what. That is, which principal can perform actions on what
resources, and under what conditions.
The Action
element of a JSON policy describes the actions that you can use to allow or deny access in a policy. Policy actions usually have the same name as the associated Amazon API operation.
Kinesis Data Streams actions that can be shared:
Action | Level of access |
---|---|
DescribeStreamConsumer | Consumer |
DescribeStreamSummary | Data stream |
GetRecords | Data stream |
GetShardIterator | Data stream |
ListShards | Data stream |
PutRecord | Data stream |
PutRecords | Data stream |
SubscribeToShard | Consumer |
Following are examples of using a resource-based policy to grant cross-account access to your data stream or registered consumer.
To perform a cross-account action, you must specify the stream ARN for data stream access and the consumer ARN for registered consumer access.
Example resource-based policies for Kinesis data streams
Sharing a registered consumer involves both a data stream policy and a consumer policy due to the actions needed.
Note
Following are examples of valid values for Principal
:
{"AWS": "123456789012"}
IAM User –
{"AWS": "arn:aws:iam::123456789012:user/user-name"}
IAM Role –
{"AWS":["arn:aws:iam::123456789012:role/role-name"]}
Multiple Principals (can be combination of account, user, role) –
{"AWS":["123456789012", "123456789013", "arn:aws:iam::123456789012:user/user-name"]}
Manage the policy for your data stream programatically
Outside of the Amazon Web Services Management Console, Kinesis Data Streams has three APIS for managing your data stream policy:
Use PutResourePolicy
to attach or overwrite a policy for a data stream or consumer. Use GetResourcePolicy
to check and view a policy for the specified data stream or consumer.
Use DeleteResourcePolicy
to delete a policy for the specified data stream or consumer.
Policy limits
Kinesis Data Streams resource policies have the following restrictions:
-
Wildcards (*) are not supported to help prevent broad access from being granted through the resource policies that are directly attached to a data stream or registered consumer. In addition, carefully inspect the following policies to confirm that they do not grant broad access:
-
Identity-based policies attached to associated Amazon principals (for example, IAM roles)
-
Resource-based policies attached to associated Amazon resources (for example, Amazon Key Management Service KMS keys)
-
Amazon Service Principals are not supported for principals to prevent potential confused deputies.
Federated principals are not supported.
Canonical user IDs are not supported.
The size of the policy cannot exceed 20KB.
Share access to encrypted data
If you have enabled server-side encryption for a data stream with Amazon managed KMS key and want to share access via a resource policy, you must switch to using customer-managed key (CMK). For more information, see What is server-side encryption for Kinesis Data Streams?. In addition, you must allow your sharing principal entities to have access to your CMK, using KMS cross account sharing capabilities. Make sure to also make the change in the IAM policies for the sharing principal entities. For more information, see Allowing users in other accounts to use a KMS key.
Configure an Amazon Lambda function to read from Kinesis Data Streams in another account
For an example of how to configure a Lambda function to read from Kinesis Data Streams in another account, see Share access with cross-account Amazon Lambda functions.