Amazon Relational Database Service
User Guide (API Version 2013-09-09)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Using AWS Identity and Access Management (IAM) to Manage Access to Amazon RDS Resources

You can use AWS IAM to create permissions that specify which Amazon RDS actions a user or group in your AWS account can perform, and on which RDS resources those actions can be performed.  You specify permissions using an IAM policy, which is a JSON document.

When you sign up for an AWS account, you receive AWS account credentials. These AWS account credentials let you perform any AWS action, including Amazon RDS API actions. For example, by using your AWS account credentials, you can create and delete DB instances. IAM policies apply to working with the Amazon RDS CLI and API as well.

Note

AWS account credentials do not grant you the ability to login to databases on a DB instance.

You should not share your AWS account credentials with other users. Instead, you should use AWS IAM to establish user identities and create permissions that specify precisely what Amazon RDS actions and resources those users have access to.

You can create permissions that manage access to the following Amazon RDS resources:

  • DB instances

  • DB snapshots

  • Read replicas

  • Reserved instances

  • DB security groups

  • DB option groups

  • DB parameter groups

  • Event subscriptions

  • DB subnet groups

To manage access to your Amazon RDS resources, you should take the following steps:

  1. Create IAM users (user identities) under your AWS account for all users who will manage your Amazon RDS resources. Each user can have a separate password (for console access) and security credentials (for programmatic and CLI access). You can organize IAM users into groups, which makes it easier to manage permissions for multiple users at a time.

  2. Determine what tasks each user and group will have regarding your Amazon RDS resources. For example, you could have groups for administrators, security personnel, DBAs, and developers.

  3. Optionally, you can tag the Amazon RDS resources you want to control access to. You can assign a tag, a key-value pair, to any Amazon RDS resource, and use that tag as a way to specify a particular resource in an IAM policy.

    Note that tagging is not available in the GovCloud region.

  4. Create the IAM policies that define the actions a user can take, and specify the Amazon RDS resources required for each task using Amazon Resource Names (ARNs). If you have used tags for your Amazon RDS resources, you can add conditions to the policy to test for those tag values.

  5. Attach the policies to the applicable users or groups.

Creating IAM Policies for Amazon RDS

By default, newly created IAM users do not have permission to access any AWS resources. This means that IAM users also can't use the Amazon RDS console or CLI. To allow IAM users to use the features of Amazon RDS, you must create IAM policies that allow users to access the required Amazon RDS API actions and resources, and then attach the policies to the IAM users or groups that require those permissions.

An IAM policy is a JSON document that consists of one or more statements. Each statement in an IAM policy is made up of elements that define what actions can be taken on what resources. The following example shows a simple policy statement that allows a user to only create a DB instance that must have "test" prefixed to the DB instance name, use the MySQL DB engine, and can only use the micro DB instance class.

{
  "Version":"2012-10-17", 
  "Statement":[
  {
    "Effect":"Allow",           
    "Action": "rds:CreateDBInstance",
    "Resource":"arn:aws:rds:us-east-1:1234567890:db:test*", 
    "Condition":
    {
      "streq":[
        {"rds:DatabaseEngine":"mysql"},
        {"rds:DatabaseClass":"db.t1.micro"}]
    }
  }]
}

The Version element is required, and the value must be "2012-10-17". The Effect element is set to either "Allow" or "Deny" . (Actions are denied by default, so you typically specify "Allow".) The Action element lists which AWS APIs the policy will allow (or deny). In this case, the Action element lists one action from the Amazon RDS API., so it will be the only action allowed by this policy statement. Note that the action is identified by both service name (rds) and action (CreateDBInstance); policies can list actions from any AWS service. You can use wildcards (*) to specify actions—for example, the action rds:Describe* would allow the user to perform any Amazon RDS action that begins with Describe ( DescribeDBInstances, DescribeDBLogFiles, DescribeDBParameterGroups, DescribeDBSnapshots, etc.) .

The Resource element lets you specify which resources the user can perform the actions on or with. In this example, the user can only create DB instances with the prefix "test" in the DB instance name. You specify resources using an Amazon Resources Name (ARN) that includes the name of the service that the resource belongs to (rds), the region (us-east-1), the account number, and the type of resource (a DB instance). For more information on creating ARNs, see Constructing an Amazon RDS Amazon Resource Name (ARN)

Finally, the optional Condition element lets you specify additional restrictions on the policy, such as date/time, source IP address, region, or tags. In this example, the Condition element indicates that the actions are allowed only on instances with the MySQL DB engine and the micro DB instance class. For more information on creating conditions, see Condition.

This policy might be attached to an individual IAM user, and in that case, that user would be allowed to perform the listed actions. You could instead attach the policy to an IAM group, and then every IAM user in that group would have these permissions.

Permissions Needed to Use the Amazon RDS Console

When users work with the Amazon RDS console, you must grant them permissions not only to perform the specific actions that you want to allow, but also permissions to actions that the console itself needs. For example, simply to list resources, the console runs the API actions such as DescribeSecurityGroups and DescribeSubnets. Users working in the console must have these permissions; if they don't, portions of the console that users need to work with might simply display a message that users don't have permissions for a task.

The following example policy statement shows permissions that users typically need in order to work in the Amazon RDS console. Notice that this includes RDS actions that start with the word "Describe," a number of EC2 and CloudWatch actions that likewise pertain to describing (listing) resources, and all SNS actions.

{
    "Version":"2012-10-17",  
    "Statement":[{
    "Effect": "Allow",
    "Action": [
        "rds:Describe*",
        "rds:ListTagsForResource",
        "ec2:DescribeAvailabilityZones",
        "ec2:DescribeVpcs",
        "ec2:DescribeAccountAttributes",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSubnets",
        "cloudwatch:GetMetricStatistics",
        "cloudwatch:DescribeAlarms",
        "sns:*"
            ],
   "Resource": "*"
   }]
}

How Resource Authorization Works in Amazon RDS

When a user requests an Amazon RDS action, an IAM authorization request is generated for every resource identified in the request. Amazon RDS checks the IAM policy for the user who is making the request. If the policy explicitly allows the user to perform the requested action on  the specified resources, then the action takes place.

An authorization request that applies to multiple resources can result in multiple resource authorizations. For example, a point-in-time-restore to a new database instance will generate two authorization requests:

  1. An authorization request will be generated for the target database instance.

  2. An authorization request will be generated for the snapshot that is being restored.

Note that a policy can, for example, limit the storage or compute size to specific values or ranges. For a fuller explanation about how an IAM policy is evaluated, see IAM Policy Evaluation Logic.

Specifying Conditions in an IAM Policy for Amazon RDS

When creating an IAM policy, you can specify conditions using two types of values. You can specifying the tag associated with a resource as a condition, or you can use a predefined key, such as the DB engine type or the DB engine class. The following tables shows the predefined keys you can use when defining IAM policy for Amazon RDS. Note that tag key/value pairs and predefined keys are case sensitive.

AWS Predefined Keys

AWS provides several predefined keys that apply to all AWS resources that support IAM policies. The following table shows the AWS predefined keys that apply to Amazon RDS resources.

AWS Predefined Key Description Value type
aws:CurrentTime The current time. Used for date conditions.Date/Time
aws:EpochTime The current time in epoch or UNIX time format. Used for date conditions.Date/Time
aws:principaltypeThe type of principal (user, account, federated user, etc.) for the current request.String
aws:SourceIp The requester's IP address (see IP Address ). Note that if you use aws:SourceIp, and the request comes from an Amazon EC2 instance, the instance's public IP address is evaluated. IP Address
aws:UserAgent The requester's client application. String
aws:userid The requester's user ID. String
aws:username The requester's user name String

Amazon RDS Predefined Keys

Amazon RDS also has predefined keys that you can include in Condition elements in an IAM policy. Amazon RDS predefined keys do not apply to all actions; the Amazon RDS predefined keys apply to the following actions:

  • CreateDBInstance

  • ModifyDBInstance

  • DeleteDBInstance

  • DescribeDBLogFiles

  • AddTagsToResource (when resource = db)

  • RemoveTagsFromResource (when resource = db)

  • RestoreDBInstanceToPointInTime

  • RestoreDBInstanceFromDBSnapshot (only the request parameters are validated)

  • DownloadDBLogFilePortion

  • DescribeDBInstance (where an instance id is passed)

The following table shows the Amazon RDS predefined keys that apply to Amazon RDS resources.

RDS Predefined Key Description Value type
rds:DatabaseClass The DB instance class of a DB instance String
rds:DatabaseEngine The DB engine of the DB instance String
rds:DatabaseName The name of the database on the DB instance String
rds:MultiAz Indicates if the DB instance is running in multiple availability zones. 1 indicates that the DB instance is using multi-AZ.Boolean
rds:Piops This key will be present when a request is made for a DB instance with PIOPs enabled. The value will contain the number of provisioned IOs that an instance supports. 0 indicates does not have PIOPs enabled.Integer
rds:StorageSize The storage volume size (in GB)Integer
rds:Vpc Indicates if the database instance is running in a virtual private cloudBoolean

Using Predefined Keys and Tags with a Condition Element

You can add your own tags to an Amazon RDS resource and use those tags in IAM policies using the Condition element. Amazon RDS resource tags are formatted slightly differently than predefined keys in a Condition element. For example, the following Condition element uses a predefined key and specifies that the condition applies to the DB engine MySQL:

“Condition":{"streq":{"rds:DatabaseEngine", "mysql" } }

The following Condition element uses an Amazon RDS tag and specifies that the condition applies to a tag with a key named environment and a value of production.

"Condition":{"streq":{"rds:db-tag/environment": [“production”]} }

The format for the tag in a Condition element is “rds:”, followed by the type of resource (in this case, “db”), a hyphen, then the tag key and tag value separated by a forward slash.

For more information about the IAM policy Condition element, see Condition.

Example IAM Policies for Amazon RDS

The following examples show simple IAM policy statements that you can use to manage the access IAM users have to Amazon RDS resources.

Example 1: Permit a user to perform any Describe action on any RDS resource

The following statement allows a user to run the describe action, which shows information about an RDS resource such as a DB instance. Note that the “*” in the Resource element indicates that the actions are allowed for all Amazon RDS resources.

{
"Version":"2012-10-17",  
"Statement":[{
"Effect":"Allow",
"Action":"rds:Describe*",
"Resource":"*"
  }]
}

Example 2: Permit a user to create a DB instance that uses a specified DB engine

The following statement uses a predefined Amazon RDS key and allows a user to create only DB instances that use the MySQL DB engine. The Condition element indicates that the DB engine requirement is MySQL.

{ 
"Version":"2012-10-17",  
"Statement":[{
"Effect":"Deny",
"Action": "rds:CreateDBInstance",
"Resource": "*",
"Condition":{"strneq":{"rds:DatabaseEngine":"mysql"}}
  }]
}

Example 3: Permit a user to create a DB instance that uses the specified DB parameter and security groups

The following statement allows a user to only create a DB instance that must use the mysql-production DB parameter group and the db-production DB security group.

{ 
"Version":"2012-10-17",  
"Statement":[{
"Effect":"Allow",            
"Action": "rds:CreateDBInstance",
"Resource": [ 
    "arn:aws:rds:us-east-1:1234567890:pg:mysql-production",
    "arn:aws:rds:us-east-1:1234567890:secgrp:db-production" ]
  }]
}

Example 4: Prevent a user from creating a DB instance that uses specified DB parameter groups

The following statement prevents a user from creating a DB instance that uses DB parameter groups with specific tag values. You might apply this policy if you require that a specific customer-created DB parameter group always be used when creating DB instances.

{ 
"Version":"2012-10-17",  
"Statement":[{
"Effect":"Deny",
"Action": "rds:CreateDBInstance",
"Resource": "*",
"Condition": {"streq": {"rds:db-tag/usage" : "prod" } }
  }]
}

Example 5: Prevent users from creating DB instances for certain DB instance classes and from creating DB instances that use Provisioned IOPS

The following statement prevents users from creating DB instances that use the DB instance classes m2.2xlarge and m2.4xlarge, which are the largest and most expensive instances. This example also prevents users from creating DB instances that use Provisioned IOPS, which is an additional cost.

 
 {
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Deny",
"Action":"rds:CreateDBInstance",
"Resource": "*",
"Condition":{"streq":{"rds:DatabaseClass":["db.m2.4xlarge", "db.m2.2xlarge"]}}
},
{
"Effect":"Deny",
"Action":"rds:CreateDBInstance",
"Resource": "*",
"Condition":{"NumericNotEquals":{"rds:Piops":"0"}}
}
]
} 

You can add a tag to an Amazon RDS resource, and then use that tag in a policy to specify a particular resource. The following examples use Amazon RDS resource tags as part of the IAM policy to specify a particular resource.

Example 6: Permits a user to perform an action on a resource tagged with two different values

This following statement allows a user to perform the ModifyDBInstance and CreateDBSnapshot actions on instances with either the “stage” tag set to “development” or “test.”

{ 
"Version":"2012-10-17",  
"Statement":[{
"Effect":"Allow",            
 
"Action": [
    "rds:ModifyDBInstance",
    "rds:CreateDBSnapshot" ],
"Resource":"*",
"Condition":{"streq":{"db-tag/stage": [ "development", "test" ] } }
  }]
}

Example 7: Permits a user to perform actions on a DB instance with a DB instance name prefixed with the user name

This following statement allows a user to perform any action (except to add or remove tags) on a DB instance that has a DB instance name that is prefixed with the user's name and that has a tag called "stage" equal to "devo" or that has no tag called "stage."

{ 
"Version":"2012-10-17",  
"Statement":[{ 
"Effect":"Allow",            
"NotAction": ["rds:AddTagsToResource","rds:RemoveTagsFromResource"],
"Resource": "arn:aws:rds:*:314195462963:db:${aws:username}*",
"Condition":{"StringEqualsIfExists":{"rds:db-tag/stage":"devo"}}
}]
}

For more information about adding tags to an Amazon RDS resource, see Constructing an Amazon RDS Amazon Resource Name (ARN). For more information about policies, see Permissions and Policies in the IAM documentation.

Sample IAM Policy for Amazon RDS

An IAM policy can apply to other AWS services; for example, this sample policy is focused on managing Amazon RDS resources but includes EC2 resources that are required for accessing information through the Amazon RDS console.

The following policy lets a user create and view all resources, modify and delete resources with a tag of environment=development or environment=test , and add a tag of environment=development or environment=test tags to any Amazon RDS resource unless the resource is already tagged with environment=production . For all resources tagged environment=production, the user cannot modify or delete these resources and they cannot grant themselves access.

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "rds:AddTagsToResource"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:req-tag/environment": [
                        "development",
                        "test"
                    ]
                },
                "strneq": {
                    "rds:db-tag/environment": [
                        "production"
                    ],
                    "rds:es-tag/environment": [
                        "production"
                    ],
                    "rds:og-tag/environment": [
                        "production"
                    ],
                    "rds:pg-tag/environment": [
                        "production"
                    ],
                    "rds:ri-tag/environment": [
                        "production"
                    ],
                    "rds:recgrp-tag/environment": [
                        "production"
                    ],
                    "rds:snapshot-tag/environment": [
                        "production"
                    ],
                    "rds:subgrp-tag/environment": [
                        "production"
                    ]
                }
            }
        },
{
            "Effect": "Allow",
            "Action": [
                "rds:RemoveTagsFromResource"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:req-tag/environment": [
                        ""
                    ]
                },
                "strneq": {
                    "rds:db-tag/environment": [
                        "production"
                    ],
                    "rds:es-tag/environment": [
                        "production"
                    ],
                    "rds:og-tag/environment": [
                        "production"
                    ],
                    "rds:pg-tag/environment": [
                        "production"
                    ],
                    "rds:ri-tag/environment": [
                        "production"
                    ],
                    "rds:recgrp-tag/environment": [
                        "production"
                    ],
                    "rds:snapshot-tag/environment": [
                        "production"
                    ],
                    "rds:subgrp-tag/environment": [
                        "production"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteDBInstance",
                "rds:ModifyDBInstance",
                "rds:CopyDBSnapshot",
                "rds:DownloadDBLogFilePortion",
                "rds:PromoteReadReplica",
                "rds:RebootDBInstance",
                "rds:RestoreDBInstanceFromDBSnapshot",
                "rds:RestoreDBInstanceToPointInTime"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:db-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteEventSubscription",
                "rds:ModifyEventSubscription",
                "rds:AddSourceIdentifierToSubscription",
                "rds:RemoveSourceIdentifierFromSubscription"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:es-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteOptionGroup",
                "rds:ModifyOptionGroup"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:og-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteDBParameterGroup",
                "rds:ModifyDBParameterGroup",
                "rds:ResetDBParameterGroup"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:pg-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteSecurityGroup",
                "rds:AuthorizeDBSecurityGroupIngress",
                "rds:RevokeDBSecurityGroupIngress"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:secgrp-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteDBSnapshot",
                "rds:CopyDBSnapshot",
                "rds:RestoreDBInstanceFromDBSnapshot",
                "rds:RestoreDBInstanceToPointInTime"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:snapshot-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:DeleteDBSubnetGroup",
                "rds:ModifyDBSubnetGroup"
            ],
            "Resource": "*",
            "Condition": {
                "streq": {
                    "rds:subgrp-tag/environment": [
                        "development",
                        "test"
                    ]
                }
            }
        },
        {
            "Effect": "Allow",
            "Action": [
                "rds:Describe*",
                "rds:Create*",
                "rds:ListTagsForResource",
                "ec2:DescribeAvailabilityZones",
                "ec2:DescribeVpcs",
                "ec2:DescribeAccountAttributes",
                "ec2:DescribeSecurityGroups",
                "ec2:DescribeSubnets",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:DescribeAlarms",
                "sns:*"
            ],
            "Resource": "*"
        }
    ]

}