# Using identity-based policies with Amazon DynamoDB
This topic covers using identity-based AWS Identity and Access Management (IAM) policies with Amazon DynamoDB and provides examples. The examples show how an account administrator can attach permissions policies to IAM identities (users, groups, and roles) and thereby grant permissions to perform operations on Amazon DynamoDB resources.
The sections in this topic cover the following:
+ [IAM permissions required to use the Amazon DynamoDB console](#console-permissions)
+ [AWS managed (predefined) IAM policies for Amazon DynamoDB](#access-policy-examples-aws-managed)
+ [Customer managed policy examples](#access-policy-examples-for-sdk-cli)
The following is an example of a permissions policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DescribeQueryScanBooksTable",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeTable",
"dynamodb:Query",
"dynamodb:Scan"
],
"Resource": "arn:aws:dynamodb:us-west-2:111122223333:table/Books"
}
]
}
```
------
The preceding policy has one statement that grants permissions for three DynamoDB actions (`dynamodb:DescribeTable`, `dynamodb:Query`, and `dynamodb:Scan`) on a table in the `us-west-2` AWS Region, which is owned by the AWS account specified by `account-id`. The *Amazon Resource Name (ARN)* in the `Resource` value specifies the table that the permissions apply to.
## IAM permissions required to use the Amazon DynamoDB console
To work with the DynamoDB console, a user must have a minimum set of permissions that allow the user to work with their AWS account's DynamoDB resources. In addition to these DynamoDB permissions, the console requires permissions:
+ Amazon CloudWatch permissions to display metrics and graphs.
+ AWS Data Pipeline permissions to export and import DynamoDB data.
+ AWS Identity and Access Management permissions to access roles necessary for exports and imports.
+ Amazon Simple Notification Service permissions to notify you whenever a CloudWatch alarm is triggered.
+ AWS Lambda permissions to process DynamoDB Streams records.
If you create an IAM policy that is more restrictive than the minimum required permissions, the console won't function as intended for users with that IAM policy. To ensure that those users can still use the DynamoDB console, also attach the `AmazonDynamoDBReadOnlyAccess` AWS managed policy to the user, as described in [AWS managed (predefined) IAM policies for Amazon DynamoDB](#access-policy-examples-aws-managed).
You don't need to allow minimum console permissions for users who are making calls only to the AWS CLI or the Amazon DynamoDB API.
**Note**
If you refer to a VPC endpoint, you will also need to authorize the DescribeEndpoints API call for the requesting IAM principal(s) with the IAM action (dynamodb:DescribeEndpoints). For more information see [Required policy for endpoints](inter-network-traffic-privacy.md#inter-network-traffic-DescribeEndpoints).
## AWS managed (predefined) IAM policies for Amazon DynamoDB
AWS addresses some common use cases by providing standalone IAM policies that are created and administered by AWS. These AWS managed policies grant necessary permissions for common use cases so that you can avoid having to investigate which permissions are needed. For more information, see [AWS Managed Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies) in the *IAM User Guide*.
The following AWS managed policies, which you can attach to users in your account, are specific to DynamoDB and are grouped by use-case scenario:
+ **AmazonDynamoDBReadOnlyAccess** – Grants read-only access to DynamoDB resources through the AWS Management Console.
+ **AmazonDynamoDBFullAccess** – Grants full access to DynamoDB resources through the AWS Management Console.
You can review these AWS managed permissions policies by signing in to the IAM console and searching for specific policies there.
**Important**
The best practice is to create custom IAM policies that grant [least-privilege ](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to the users, roles, or groups that require them.
## Customer managed policy examples
In this section, you can find policy examples that grant permissions for various DynamoDB actions. These policies work when you use AWS SDKs or the AWS CLI. When you use the console, you need to grant additional permissions that are specific to the console. For more information, see [IAM permissions required to use the Amazon DynamoDB console](#console-permissions).
**Note**
All of the following policy examples use one of the AWS Regions and contain fictitious account IDs and table names.
Examples:
+ [IAM policy to grant permissions to all DynamoDB actions on a table](grant-permissions-to-any-action-on-table.md)
+ [IAM policy to grant read-only permissions on items in a DynamoDB table](read-only-permissions-on-table-items.md)
+ [IAM policy to grant access to a specific DynamoDB table and its indexes](iam-policy-specific-table-indexes.md)
+ [IAM policy to read, write, update, and delete access on a DynamoDB table](iam-policy-example-data-crud.md)
+ [IAM policy to separate DynamoDB environments in the same AWS account](iam-policy-separate-environments.md)
+ [IAM policy to prevent the purchase of DynamoDB reserved capacity](iam-prevent-purchase-reserved-capacity.md)
+ [IAM policy to grant read access for a DynamoDB stream only (not for the table)](iam-policy-read-stream-only.md)
+ [IAM policy to allow an AWS Lambda function to access DynamoDB stream records](iam-policy-example-lamda-process-dynamodb-streams.md)
+ [IAM policy for read and write access to a DynamoDB Accelerator (DAX) cluster](iam-policy-example-read-write-dax-access.md)
The *IAM User Guide*, includes [three additional DynamoDB examples](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_examples.html):
+ [Amazon DynamoDB: Allows Access to a Specific Table](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_dynamodb_specific-table.html)
+ [Amazon DynamoDB: Allows Access to Specific Columns](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_dynamodb_columns.html)
+ [Amazon DynamoDB: Allows Row-Level Access to DynamoDB Based on an Amazon Cognito ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_dynamodb_rows.html)
# IAM policy to grant permissions to all DynamoDB actions on a table
The following policy grants permissions for *all* DynamoDB actions on a table called `Books`. The resource ARN specified in the `Resource` identifies a table in a specific AWS Region. If you replace the table name `Books` in the `Resource` ARN with a wildcard character (\$1), *all* DynamoDB actions are allowed on *all* tables in the account. Carefully consider the possible security implications before using a wildcard character on this or any IAM policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllAPIActionsOnBooks",
"Effect": "Allow",
"Action": "dynamodb:*",
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
}
]
}
```
------
**Note**
This is an example of using a wildcard character (\$1) to allow *all* actions, including administration, data operations, monitoring, and purchase of DynamoDB reserved capacity. Instead, it is a best practice to explicitly specify each action to be granted and only what that user, role, or group needs.
# IAM policy to grant read-only permissions on items in a DynamoDB table
The following permissions policy grants permissions for the `GetItem`, `BatchGetItem`, `Scan`, `Query`, and `ConditionCheckItem` DynamoDB actions only, and as a result, sets read-only access on the `Books` table.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ReadOnlyAPIActionsOnBooks",
"Effect": "Allow",
"Action": [
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:ConditionCheckItem"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
}
]
}
```
------
# IAM policy to grant access to a specific DynamoDB table and its indexes
The following policy grants permissions for data modification actions on a DynamoDB table called `Books` and all of that table's indexes. For more information about how indexes work, see [Improving data access with secondary indexes in DynamoDB](SecondaryIndexes.md).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessTableAllIndexesOnBooks",
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:BatchWriteItem",
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:ConditionCheckItem"
],
"Resource": [
"arn:aws:dynamodb:us-west-2:123456789012:table/Books",
"arn:aws:dynamodb:us-west-2:123456789012:table/Books/index/*"
]
}
]
}
```
------
# IAM policy to read, write, update, and delete access on a DynamoDB table
Use this policy if you need to allow your application to create, read, update, and delete data in Amazon DynamoDB tables, indexes, and streams. Substitute the AWS Region name, your account ID, and the table name or wildcard character (\$1) where appropriate.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "DynamoDBIndexAndStreamAccess",
"Effect": "Allow",
"Action": [
"dynamodb:GetShardIterator",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:DescribeStream",
"dynamodb:GetRecords",
"dynamodb:ListStreams"
],
"Resource": [
"arn:aws:dynamodb:us-west-2:123456789012:table/Books/index/*",
"arn:aws:dynamodb:us-west-2:123456789012:table/Books/stream/*"
]
},
{
"Sid": "DynamoDBTableAccess",
"Effect": "Allow",
"Action": [
"dynamodb:BatchGetItem",
"dynamodb:BatchWriteItem",
"dynamodb:ConditionCheckItem",
"dynamodb:PutItem",
"dynamodb:DescribeTable",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:UpdateItem"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
},
{
"Sid": "DynamoDBDescribeLimitsAccess",
"Effect": "Allow",
"Action": "dynamodb:DescribeLimits",
"Resource": [
"arn:aws:dynamodb:us-west-2:123456789012:table/Books",
"arn:aws:dynamodb:us-west-2:123456789012:table/Books/index/*"
]
}
]
}
```
------
To expand this policy to cover all DynamoDB tables in all AWS Regions for this account, use a wildcard (\$1) for the Region and table name. For example:
```
"Resource":[
"arn:aws:dynamodb:*:123456789012:table/*",
"arn:aws:dynamodb:*:123456789012:table/*/index/*"
]
```
# IAM policy to separate DynamoDB environments in the same AWS account
Suppose that you have separate environments where each environment maintains its own version of a table named `ProductCatalog`. If you create two `ProductCatalog` tables in the same AWS account, work in one environment might affect the other environment because of the way that permissions are set up. For example, quotas on the number of concurrent control plane operations (such as `CreateTable`) are set at the AWS account level.
As a result, each action in one environment reduces the number of operations available in the other environment. There is also a risk that the code in one environment might accidentally access tables in the other environment.
**Note**
If you want to separate production and test workloads to help control an event's potential "blast radius," the best practice is to create separate AWS accounts for test and production workloads. For more information, see [AWS Account Management and Separation](https://docs.aws.amazon.com//wellarchitected/latest/security-pillar/aws-account-management-and-separation.html).
Suppose further that you have two developers, Amit and Alice, who are testing the `ProductCatalog` table. Instead of each developer requiring a separate AWS account, your developers can share the same test AWS account. In this test account, you can create a copy of the same table for each developer to work on, such as `Alice_ProductCatalog` and `Amit_ProductCatalog`. In this case, you can create users Alice and Amit in the AWS account that you created for the test environment. You then can grant permissions to these users to perform DynamoDB actions on the tables that they own.
To grant these IAM user permissions, you can do either of the following:
+ Create a separate policy for each user, and then attach each policy to its user separately. For example, you can attach the following policy to user Alice to allow her access to DynamoDB actions on the `Alice_ProductCatalog` table:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllAPIActionsOnAliceTable",
"Effect": "Allow",
"Action": [
"dynamodb:DeleteItem",
"dynamodb:DescribeContributorInsights",
"dynamodb:RestoreTableToPointInTime",
"dynamodb:ListTagsOfResource",
"dynamodb:CreateTableReplica",
"dynamodb:UpdateContributorInsights",
"dynamodb:CreateBackup",
"dynamodb:DeleteTable",
"dynamodb:UpdateTableReplicaAutoScaling",
"dynamodb:UpdateContinuousBackups",
"dynamodb:TagResource",
"dynamodb:DescribeTable",
"dynamodb:GetItem",
"dynamodb:DescribeContinuousBackups",
"dynamodb:BatchGetItem",
"dynamodb:UpdateTimeToLive",
"dynamodb:BatchWriteItem",
"dynamodb:ConditionCheckItem",
"dynamodb:UntagResource",
"dynamodb:PutItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:UpdateItem",
"dynamodb:DeleteTableReplica",
"dynamodb:DescribeTimeToLive",
"dynamodb:RestoreTableFromBackup",
"dynamodb:UpdateTable",
"dynamodb:DescribeTableReplicaAutoScaling",
"dynamodb:GetShardIterator",
"dynamodb:DescribeStream",
"dynamodb:GetRecords",
"dynamodb:DescribeLimits",
"dynamodb:ListStreams"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Alice_ProductCatalog/*"
}
]
}
```
------
Then, you can create a similar policy with a different resource (the `Amit_ProductCatalog` table) for user Amit.
+ Instead of attaching policies to individual users, you can use IAM policy variables to write a single policy and attach it to a group. You need to create a group and, for this example, add both users Alice and Amit to the group. The following example grants permissions to perform all DynamoDB actions on the `${aws:username}_ProductCatalog` table. The policy variable `${aws:username}` is replaced by the requester's user name when the policy is evaluated. For example, if Alice sends a request to add an item, the action is allowed only if Alice is adding items to the `Alice_ProductCatalog` table.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "ActionsOnUserSpecificTable",
"Effect": "Allow",
"Action": [
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:DeleteItem",
"dynamodb:BatchWriteItem",
"dynamodb:GetItem",
"dynamodb:BatchGetItem",
"dynamodb:Scan",
"dynamodb:Query",
"dynamodb:ConditionCheckItem"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/${aws:username}_ProductCatalog"
},
{
"Sid": "AdditionalPrivileges",
"Effect": "Allow",
"Action": [
"dynamodb:ListTables",
"dynamodb:DescribeTable",
"dynamodb:DescribeContributorInsights"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/*"
}
]
}
```
------
**Note**
When using IAM policy variables, you must explicitly specify the `2012-10-17` version of the IAM policy language in the policy. The default version of the IAM policy language (`2008-10-17`) does not support policy variables.
Instead of identifying a specific table as a resource as you normally would, you could use a wildcard character (\$1) to grant permissions on all tables where the table name is prefixed with the user that is making the request, as shown in the following example.
```
"Resource":"arn:aws:dynamodb:us-west-2:123456789012:table/${aws:username}_*"
```
# IAM policy to prevent the purchase of DynamoDB reserved capacity
With Amazon DynamoDB reserved capacity, you pay a one-time, upfront fee and commit to paying for a minimum usage level at significant savings over a period of time. You can use the AWS Management Console to view and purchase reserved capacity. However, you might not want all of the users in your organization to be able to purchase reserved capacity. For more information about reserved capacity, see [Amazon DynamoDB pricing](https://aws.amazon.com/dynamodb/pricing).
DynamoDB provides the following API operations for controlling access to reserved capacity management:
+ `dynamodb:DescribeReservedCapacity` – Returns the reserved capacity purchases that are currently in effect.
+ `dynamodb:DescribeReservedCapacityOfferings` – Returns details about the reserved capacity plans that are currently offered by AWS.
+ `dynamodb:PurchaseReservedCapacityOfferings` – Performs an actual purchase of reserved capacity.
The AWS Management Console uses these API actions to display reserved capacity information and make purchases. You cannot call these operations from an application program because they can be accessed only from the console. However, you can allow or deny access to these operations in an IAM permissions policy.
The following policy allows users to view reserved capacity purchases and offerings by using the AWS Management Console — but new purchases are denied.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowReservedCapacityDescriptions",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeReservedCapacity",
"dynamodb:DescribeReservedCapacityOfferings"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:*"
},
{
"Sid": "DenyReservedCapacityPurchases",
"Effect": "Deny",
"Action": "dynamodb:PurchaseReservedCapacityOfferings",
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:*"
}
]
}
```
------
Note that this policy uses the wildcard character (\$1) to allow describe permissions for all, and to deny the purchase of DynamoDB reserved capacity for all.
# IAM policy to grant read access for a DynamoDB stream only (not for the table)
When you enable DynamoDB Streams on a table, information is captured about every modification to items in the table. For more information, see [Change data capture for DynamoDB Streams](Streams.md).
In some cases, you might want to prevent an application from reading data from a DynamoDB table, but still allow access to that table's streams. For example, you can configure AWS Lambda to poll a stream and invoke a Lambda function when item updates are detected, and then perform additional processing.
The following actions are available for controlling access to DynamoDB streams:
+ `dynamodb:DescribeStream`
+ `dynamodb:GetRecords`
+ `dynamodb:GetShardIterator`
+ `dynamodb:ListStreams`
The following example policy grants users permissions to access the streams of a table named `GameScores`. The wildcard character (\$1) in the ARN matches any stream associated with that table.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AccessGameScoresStreamOnly",
"Effect": "Allow",
"Action": [
"dynamodb:DescribeStream",
"dynamodb:GetRecords",
"dynamodb:GetShardIterator",
"dynamodb:ListStreams"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/stream/*"
}
]
}
```
------
Note that this policy grants access to the `GameScores` table's streams, but not to the table itself.
# IAM policy to allow an AWS Lambda function to access DynamoDB stream records
If you want certain actions to be performed based on events in a DynamoDB stream, you can write an AWS Lambda function that is triggered by these events. A Lambda function such as this needs permissions to read data from a DynamoDB stream. For more information about using Lambda with DynamoDB Streams, see [DynamoDB Streams and AWS Lambda triggers](Streams.Lambda.md).
To grant permissions to Lambda, use the permissions policy that is associated with the Lambda function's IAM role (also known as an execution role). Specify this policy when you create the Lambda function.
For example, you can associate the following permissions policy with an execution role to grant Lambda permissions to perform the DynamoDB Streams actions listed.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "APIAccessForDynamoDBStreams",
"Effect": "Allow",
"Action": [
"dynamodb:GetRecords",
"dynamodb:GetShardIterator",
"dynamodb:DescribeStream",
"dynamodb:ListStreams"
],
"Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/stream/*"
}
]
}
```
------
For more information, see [AWS Lambda permissions ](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html) in the *AWS Lambda Developer Guide*.
# IAM policy for read and write access to a DynamoDB Accelerator (DAX) cluster
The following policy allows read, write, update, and delete access to a DynamoDB Accelerator (DAX) cluster, but not to the associated DynamoDB table. To use this policy, substitute the AWS Region name, your account ID, and the name of your DAX cluster.
**Note**
This policy gives access to DAX cluster, but not to the associated DynamoDB table. Make sure that your DAX cluster has the correct policy to perform these same operations on the DynamoDB table on your behalf.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AmazonDynamoDBDAXDataOperations",
"Effect": "Allow",
"Action": [
"dax:GetItem",
"dax:PutItem",
"dax:ConditionCheckItem",
"dax:BatchGetItem",
"dax:BatchWriteItem",
"dax:DeleteItem",
"dax:Query",
"dax:UpdateItem",
"dax:Scan"
],
"Resource": "arn:aws:dax:eu-west-1:123456789012:cache/MyDAXCluster"
}
]
}
```
------
To expand this policy to cover DAX access for all AWS Regions for an account, use a wildcard character (\$1) for the Region name.
```
"Resource": "arn:aws:dax:*:123456789012:cache/MyDAXCluster"
```