Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

Authentication and Access Control for Amazon DynamoDB

Access to DynamoDB requires credentials that AWS can use to authenticate your requests. Those credentials must have permissions to access AWS resources. This section provides details on how you can use AWS Identity and Access Management (IAM) and DynamoDB to help secure your resources by controlling who can access them.

Authentication

When you sign up for AWS, you provide an email address and password that are associated with your AWS account. These are your root credentials and they provide complete access to all of your AWS resources.

When you create your AWS account, for security reasons we recommend that you use these root credentials for the first time only to create an administrator user with full permissions to your AWS account. For instructions, see Creating an Administrators Group in the IAM User Guide. You can then use this administrator user to create other IAM users and roles with limited permissions.

An IAM user is simply an identity within your AWS account that you create in the IAM service that has specific custom permissions (for example, to upload objects to an Amazon S3 bucket, read items from a specific DynamoDB table, or create an Amazon RDS database instance). You can use an IAM user name and password to sign in to secure AWS webpages like the AWS Management Console, AWS Discussion Forums, and the AWS Support Center.

You can also generate access keys for each user that can be used to authenticate requests when accessing AWS services programmatically, either through one of the several SDKs or by using the AWS Command Line Interface (CLI). Using the access keys you provide, the SDK and CLI tools cryptographically sign your request. If you don’t use the AWS tools, you must sign the request yourself. DynamoDB supports Signature Version 4, a protocol for authenticating inbound API requests. For more information about authenticating requests, see Signature Version 4 Signing Process in the Amazon Web Services General Reference.

Instead of creating an IAM user, you can also use pre-existing user identities from AWS Directory Service, your enterprise user directory, or a web identity provider. These user identities are referred to as federated users. Federated users access AWS services and resources through an IAM role, which is similar to an IAM user, but is not associated with a specific person. Instead, a role is assigned to a federated user dynamically when the user requests access through an identity provider. Note that IAM roles can also be used for other purposes, such as granting other AWS accounts permissions to access your account’s resources. A federated user is associated with an IAM role that enables the user to obtain temporary access keys, which the user uses to authenticate requests. For more information about federated users, see Federated Users and Roles in the IAM User Guide.

Access Control

DynamoDB supports identity-based permissions policies, in which you attach a permissions policy to an IAM identity (that is, a user, a group, or an IAM role). For more information about permissions policies, see Overview of AWS IAM Permissions in the IAM User Guide.

Note

Other services, such as Amazon S3, also support resource-based permissions policies. For example, you can attach a policy to an S3 bucket to manage access permissions to that bucket. DynamoDB does not support resource-based permissions policies.

Users and roles can get valid credentials, but they don’t have any permissions by default. You need to grant permissions by creating permissions policies and then attaching them to a user, a group, or an IAM role. A policy determines which AWS API actions a user can perform on which AWS resources.

You can create a permissions policy to grant resource access permissions to users in your account or cross-account permissions. For example, the administrator in Account A can create a role that has permissions to access Account A’s resources, and then specify Account B as a principal in this role’s trust policy. Then, the administrator in Account B can delegate permissions to assume the role to any of the users in Account B. What the Account B principal entity can do by assuming this role is limited by the permissions policy associated with the role. You can also grant permissions to other AWS services. For more information about using IAM to delegate permissions, see Access Management in the IAM User Guide. A complete tutorial is available at Walkthrough: Delegating Access Across AWS Accounts For Accounts You Own Using IAM Roles.

Understanding Resource Ownership

A resource owner is the AWS account that created a resource. That is, the resource owner is the AWS account of the principal entity (the root account, an IAM user, or an IAM role) that authenticates the request that creates the resource. The following examples illustrate how this works:

  • If you use the root account credentials of your AWS account to create a table, your AWS account is the owner of the table resource (in DynamoDB, a resource can be a table or an index).

  • If you create an IAM user in your AWS account and grant permissions to that use to create a table, the user can create a table. However, your AWS account, to which the user belongs, owns the table resource.

  • If you create an IAM role in your AWS account with permissions to create a table, anyone who can assume the role can create a table. Again, your AWS account, to which the role belongs, owns the table resource.

Managing Access

To create or access resources using the API, an IAM user or role must be granted permissions through a permissions policy. For example, to grant a user permissions to create a table, you use a permissions policy that is associated with that user.

You can use IAM roles in cross-account scenarios. For example, Account A can create an IAM role that allows Account B to access resources in Account A's account. Then, Account B can assume that role and access resources in Account A. However, what the Account B principal entity can do by assuming the role is limited by the permissions policy associated with the role.

For more information about users, groups, roles, and permissions, see Identities (Users, Groups, and Roles), IAM Roles, and Access Management in the IAM User Guide.

The following shows an example of a permissions policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QueryAndScanBooksTable",
            "Effect": "Allow",
            "Action": [
                "dynamodb:Query",
                "dynamodb:Scan"
            ],
            "Resource": "arn:aws:dynamodb:us-west-2:account-id:table/Books"
        },
        {
            "Sid": "ListAndDescribeAllTables",
            "Effect": "Allow",
            "Action": [
                "dynamodb:ListTables",
                "dynamodb:DescribeTable"
            ],
            "Resource": "arn:aws:dynamodb:us-west-2:account-id:table/*"
        }
    ]
}

The policy has two statements (note the Action and Resource elements in both the statements):

  • The first statement grants permissions for two DynamoDB actions (dynamodb:Query and dynamodb:Scan) on a table in the us-west-2 region, which is owned by the AWS account specified by account-id. The Amazon Resource Name (ARN) in the Resource value specifies the table to which the permissions apply.

    Note

    ARNs uniquely identify AWS resources. For more information, see Amazon Resource Names (ARNs) and AWS Service Namespaces in the AWS General Reference.

  • The second statement grants permissions for two DynamoDB actions (dynamodb:ListTables and dynamodb:DescribeTable). The wildcard character (*) in the Resource value ("table/*") means that you can use these actions on any table in the us-west-2 region that is owned by the AWS account specified by account-id.

Specifying Actions and Resources

In DynamoDB, a table is the primary resource. DynamoDB supports allowing other resources to configure the primary resource. We can think of these other resources as subresources that don't exist unless they are associated with a table. In DynamoDB, there are three types of resources: table, index, and stream. The following table shows each type of resource in Amazon DynamoDB with the ARN format.

Resource TypeARN Format
Table arn:aws:dynamodb:region:account-id:table/table-name
Index arn:aws:dynamodb:region:account-id:table/table-name/index/index-name
Stream arn:aws:dynamodb:region:account-id:table/table-name/stream/stream-label

To grant permissions for specific API operations, such as creating or deleting a table, DynamoDB defines a set of actions that you can specify in a permissions policy. An API operation can require permissions for more than one action. For a table showing all of the DynamoDB API operations, the corresponding actions for which permissions are required, and the AWS resources for which you can grant the permissions to perform the action, see DynamoDB API Permissions: Actions, Resources, and Conditions Reference.

For all of these DynamoDB actions, the Resource value specifies the table, index, or stream on which you want to grant the permissions. You specify the Resource value using the resource’s ARN.

For example, to allow a user to read an item from a table by using the item's primary key (dynamodb:GetItem), you specify its table name in the ARN, as shown following:

arn:aws:dynamodb:region:account-id:table/table-name

To allow a user to query an index (dynamodb:Query), you specify the table name and the index name in the ARN, as shown following:

arn:aws:dynamodb:region:account-id:table/table-name/index/index-name

To allow a user to read records from a stream (dynamodb:GetRecords), you specify the table name and the stream label in the ARN, as shown following:

arn:aws:dynamodb:region:account-id:table/table-name/stream/stream-label

To match any table name, index name, or stream label, use a wildcard character (*) in the ARN to match any table name, index name, or stream label, as shown following:

arn:aws:dynamodb:region:account-id:table/*

arn:aws:dynamodb:region:account-id:table/table-name/index/*

arn:aws:dynamodb:region:account-id:table/table-name/stream/*

Specifying Conditions in a Policy

When you grant permissions, you can use the access policy language to specify the conditions when a policy should take effect. For example, you might want a policy to be applied only after a specific date. For more information about specifying conditions in an access policy language, see Condition in the IAM User Guide.

To express conditions, you use predefined condition keys. DynamoDB provides several condition keys. For more information, see Using IAM Policy Conditions for Fine-Grained Access Control.

In addition to the specific DynamoDB condition keys, you can also use AWS-wide condition keys. For a complete list of AWS-wide keys, see Available Keys in the IAM User Guide.

Permissions Required to Use the DynamoDB Console

To use the DynamoDB console, you need to grant permissions for additional actions as shown in the following permissions policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DynamoDBConsolePermissions",
            "Action": [
                "dynamodb:*",
                "cloudwatch:DeleteAlarms",
                "cloudwatch:DescribeAlarmHistory",
                "cloudwatch:DescribeAlarms",
                "cloudwatch:DescribeAlarmsForMetric",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:ListMetrics",
                "cloudwatch:PutMetricAlarm",
                "datapipeline:ActivatePipeline",
                "datapipeline:CreatePipeline",
                "datapipeline:DeletePipeline",
                "datapipeline:DescribeObjects",
                "datapipeline:DescribePipelines",
                "datapipeline:GetPipelineDefinition",
                "datapipeline:ListPipelines",
                "datapipeline:PutPipelineDefinition",
                "datapipeline:QueryObjects",
                "iam:ListRoles",
                "sns:CreateTopic",
                "sns:DeleteTopic",
                "sns:ListSubscriptions",
                "sns:ListSubscriptionsByTopic",
                "sns:ListTopics",
                "sns:Subscribe",
                "sns:Unsubscribe"
            ],
            "Effect": "Allow",
            "Resource": "*"
        }
    ]
}

In addition to the dynamodb permissions, the console requires cloudwatch permissions to display Amazon CloudWatch metrics and graphs. The datapipeline permissions allow you to use the console to export and import DynamoDB data using AWS Data Pipeline. The iam:ListRoles permission lets the console ensure that you have access to the IAM roles necessary for exports and imports. Finally, the sns permissions allow the console to notify you by using Amazon Simple Notification Service (Amazon SNS) whenever a CloudWatch alarm is triggered.

AWS Managed Policies for DynamoDB

AWS addresses many common use cases for IAM policies by providing AWS managed policies. An AWS managed policy is a standalone policy that is created and administered by AWS. For more information about AWS managed policies, see AWS Managed Policies in the IAM User Guide.

The following AWS managed policies are specific to Amazon DynamoDB and are provided in the IAM console.

  • AmazonDynamoDBReadOnlyAccess – Grants read-only access to DynamoDB resources by using the AWS Management Console.

  • AmazonDynamoDBFullAccess – Grants full access to DynamoDB resources by using the AWS Management Console.

  • AmazonDynamoDBFullAccesswithDataPipeline – Grants full access to DynamoDB resources, including export and import using AWS Data Pipeline, by using AWS Management Console.

You can also create custom IAM policies that allow users to access the required DynamoDB API actions and resources, and then attach the policies to the IAM users or groups that require those permissions. For more information, see Example Policies: Creating Your Own Permissions Policies.

Example Policies: Creating Your Own Permissions Policies

In this section, you can find example user policies that grant permissions for various DynamoDB actions. These policies work when you are using AWS SDKs or the AWS CLI. When you are using the console, you need to grant additional permissions specific to the console, which is discussed in Permissions Required to Use the DynamoDB Console.

Note

All examples use the us-west-2 region and contain fictitious account IDs.

Example 1: Grant Permissions to Allow Any DynamoDB Actions on a Table

The following permissions policy grants permissions for all DynamoDB actions on a table. The ARN value specified in the Resource identifies a table in a specific region.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllAPIActionsOnBooks",
            "Effect": "Allow",
            "Action": "dynamodb:*",
            "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
        }
    ]
}

Note

If you replace the table name in the resource ARN (Books) with a wildcard character (*) , you allow any DynamoDB actions on all tables in the account. Carefully consider the security implications if you decide to do this.

Example 2: Grant Permissions to Allow Read-only Access on Items in a Table

The following permissions policy grants permissions for the GetItem and BatchGetItem DynamoDB actions only and thereby sets read-only access to a table.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ReadOnlyAPIActionsOnBooks",
            "Effect": "Allow",
            "Action": [
                "dynamodb:GetItem",
                "dynamodb:BatchGetItem"
            ],
            "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
        }
    ]
}

Example 3: Grant Permissions to Allow Put, Update, and Delete Operations on a Specific Table

The following permissions policy grants permissions for the PutItem, UpdateItem, and DeleteItem actions on a specific DynamoDB table.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PutUpdateDeleteOnBooks",
            "Effect": "Allow",
            "Action": [
                "dynamodb:PutItem",
                "dynamodb:UpdateItem",
                "dynamodb:DeleteItem"
            ],
            "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Books"
        }
    ]
}

Example 4: Grant Permissions to Allow Access to a Specific Table and All of Its Indexes

The following permissions policy grants permissions for all of the DynamoDB actions on a table (Book) and all of the table's indexes. For more information about how indexes work, see Improving Data Access with Secondary Indexes in DynamoDB.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AccessAllIndexesOnBooks",
            "Effect": "Allow",
            "Action": [
                "dynamodb:*"
            ],
            "Resource": [
                "arn:aws:dynamodb:us-west-2:123456789012:table/Books",
                "arn:aws:dynamodb:us-west-2:123456789012:table/Books/index/*"
            ]
        }
    ]
}

Example 5: Set Up Permissions Policies for Separate Test and Production Environments

Suppose you have separate test and production environments where each environment maintains its own version of a table named ProductCatalog . If you create these ProductCatalog tables from the same AWS account, testing work might affect the production environment because of the way that permissions are set up (for example, the limits on concurrent create and delete actions are set at the AWS account level). As a result, each action in the test environment reduces the number of actions that are available in your production environment. There is also a risk that the code in your test environment might accidentally access tables in the production environment. To prevent these issues, consider creating separate AWS accounts for your production and test environments.

Suppose further that you have two developers, Bob and Alice, who are testing the ProductCatalog table. Instead of creating a separate AWS account for every developer, your developers can share the same test 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 Bob_ProductCatalog . In this case, you can create IAM users Alice and Bob in the AWS account that you created for the test environment. You can then grant permissions to these users to perform DynamoDB actions on the tables that they own.

To grant these 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 all DynamoDB actions on the Alice_ProductCatalog table:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllAPIActionsOnAliceTable",
                "Effect": "Allow",
                "Action": [
                    "dynamodb:*"
                ],
                "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/Alice_ProductCatalog"
            }
        ]
    }

    Then, you can create a similar policy with a different resource (Bob_ProductCatalog table) for user Bob.

  • 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 user Bob 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.

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "AllAPIActionsOnUserSpecificTable",
                "Effect": "Allow",
                "Action": [
                    "dynamodb:*"
                ],
                "Resource": "arn:aws:dynamodb:us-west-2:123456789012:table/${aws:username}_ProductCatalog"
            },
            {
                "Sid": "AdditionalPrivileges",
                "Effect": "Allow",
                "Action": [
                    "dynamodb:ListTables",
                    "dynamodb:DescribeTable",
                    "cloudwatch:*",
                    "sns:*"
                ],
                "Resource": "*"
            }
        ]
    }

Note

When using IAM policy variables, you must explicitly specify the 2012-10-17 version of the access policy language in the policy. The default version of the access policy language (2008-10-17) does not support policy variables.

Note that, instead of identifying a specific table as a resource, you can use a wildcard character (*) to grant permissions on all tables where the name is prefixed with the name of the IAM user that is making the request, as shown following:

"Resource":"arn:aws:dynamodb:us-west-2:123456789012:table/${aws:username}_*"


Example 6: Grant Permissions to Prevent Purchasing of Reserved Capacity Offerings

DynamoDB customers can purchase reserved capacity, as described at Amazon DynamoDB Pricing. With 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 have the same levels of access.

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 operations to display reserved capacity information and to make purchases. You cannot call these operations from an application program, because they are only accessible 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 offerings and current purchases using the AWS Management Console—but new purchases are denied.

{
    "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:*"
        }
    ]
}

Example 7: Grant Permissions to Allow Read Access for a DynamoDB Stream Only (Not for the Table)

When you enable DynamoDB Streams on a table, it captures information about every modification to data items in the table. For more information, see Capturing Table Activity with DynamoDB Streams.

In some cases, you might want to prevent an application from reading data from a DynamoDB table, while still allowing access to that table's stream. For example, you can configure AWS Lambda to poll the 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 Streams:

  • dynamodb:DescribeStream

  • dynamodb:GetRecords

  • dynamodb:GetShardIterator

  • dynamodb:ListStreams

These actions correspond to the DynamoDB Streams API. For more information, see Amazon DynamoDB Streams API Reference.

The following example creates a policy that grants users permissions to access the streams on a table named GameScores. The final wildcard character (*) in the ARN matches any stream ID associated with that table.

{
    "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 permits access to the streams on the GameScores table, but not to the table itself.


Example 8: Grant Permissions to Allow an AWS Lambda Function to Process DynamoDB Stream Records

If you want certain actions to be performed based on new events in a DynamoDB stream, you can write an AWS Lambda function that is triggered by these new events. For more information about using Lambda with stream events, see Amazon DynamoDB Triggers. A Lambda function such as this needs permissions to read data from the DynamoDB stream.

To grant permissions to Lambda, you use the permissions policy that is associated with the Lambda function's IAM role (execution role), which you specify when you create the Lambda function.

For example, you can associate the following permissions policy with the execution role to grant Lambda permissions to perform the DynamoDB Streams actions listed.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowLambdaFunctionInvocation",
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction"
            ],
            "Resource": [
                "*"
            ]
        },
        {
            "Sid": "AllAPIAccessForDynamoDBStreams",
            "Effect": "Allow",
            "Action": [
                "dynamodb:GetRecords",
                "dynamodb:GetShardIterator",
                "dynamodb:DescribeStream",
                "dynamodb:ListStreams"
            ],
            "Resource": "*"
        }
    ]
}

For more information, see AWS Lambda Permission Model in the AWS Lambda Developer Guide.