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 account access that lets you use AWS IAM to establish user identities and create permissions that specify precisely what Amazon RDS actions and resources your users have access to. Your account access lets you create a DB instance and provide a master user name and master password to the instance. You use the master user name and master password to access the DB instance and create database resources and to set up users on the DB instance.

You should not share your AWS account information with anyone. For more information about managing your AWS account information, see  Best Practices for Managing AWS Keys and IAM Best Practices.

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 access keys (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..

  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 that have 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. You can also attach the policy to a role so that delegated or federated users could perform the action.

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 is allowed; otherwise, the action is denied.

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 be used to limit the possible values a resource can have. For example, storage or compute size can be limited 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 in two ways. You can create a condition that is based on a tag associated with a resource, 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

  • RemoveTagsFromResource

  • RestoreDBInstanceToPointInTime

  • RestoreDBInstanceFromDBSnapshot

  • DownloadDBLogFilePortion

  • DescribeDBInstances

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.Integer
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 then create policies that use the tag values in determining whether to grant or deny access. 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"]} }

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 all the actions whose names begin with "Describe," 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":"Allow",
"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. Note that statements that use Deny are most often used to restrict access that was granted by a broader statement.

{ 
"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.