# Configuring access policies for Performance Insights
Performance Insights policies

To access Performance Insights, a principal must have the appropriate permissions from Amazon Identity and Access Management (IAM).

**Note**  
To use Performance Insights with a customer-managed key, grant users the `kms:Decrypt` and `kms:GenerateDataKey` permissions for your Amazon Amazon KMS key.

Access Performance Insights using these methods:
+ [Attach the `AmazonRDSPerformanceInsightsReadOnly` managed policy for read-only access](USER_PerfInsights.access-control.managed-policy.md)
+ [Attach the `AmazonRDSPerformanceInsightsFullAccess` managed policy for access to all operations of the Performance Insights API](USER_PerfInsights.access-control.FullAccess-managed-policy.md)
+ [Create a custom IAM policy with specific permissions](USER_PerfInsights.access-control.custom-policy.md)
+ [Configure Amazon KMS permissions for encrypted Performance Insights data](USER_PerfInsights.access-control.cmk-policy.md)
+ [Set up fine-grained access using resource-level permissions](USER_PerfInsights.access-control.dimensionAccess-policy.md)
+ [Use tag-based access control to manage permissions through resource tags](USER_PerfInsights.access-control.tag-based-policy.md)

# Attaching the AmazonRDSPerformanceInsightsReadOnly policy to an IAM principal


`AmazonRDSPerformanceInsightsReadOnly` is an Amazon managed policy that grants access to all read-only operations of the Amazon RDS Performance Insights API. 

If you attach `AmazonRDSPerformanceInsightsReadOnly` to a permission set or role, you must also attach the following CloudWatch permissions:
+ `GetMetricStatistics`
+ `ListMetrics`
+ `GetMetricData`

With these permissions, the recipient can use Performance Insights with other console features.

 For more information about CloudWatch permissions, see [Amazon CloudWatch permissions reference](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html).

For more information about `AmazonRDSPerformanceInsightsReadOnly`, see [Amazon managed policy: AmazonRDSPerformanceInsightsReadOnly](rds-security-iam-awsmanpol.md#rds-security-iam-awsmanpol-AmazonRDSPerformanceInsightsReadOnly).

# Attaching the AmazonRDSPerformanceInsightsFullAccess policy to an IAM principal


`AmazonRDSPerformanceInsightsFullAccess` is an Amazon managed policy that grants access to all operations of the Amazon RDS Performance Insights API.

If you attach `AmazonRDSPerformanceInsightsFullAccess` to a permission set or role, you must also attach the following CloudWatch permissions:
+ `GetMetricStatistics`
+ `ListMetrics`
+ `GetMetricData`

With these permissions, the recipient can use Performance Insights with other console features.

 For more information about CloudWatch permissions, see [Amazon CloudWatch permissions reference](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/permissions-reference-cw.html).

For more information about `AmazonRDSPerformanceInsightsFullAccess`, see [Amazon managed policy: AmazonRDSPerformanceInsightsFullAccess](rds-security-iam-awsmanpol.md#rds-security-iam-awsmanpol-AmazonRDSPerformanceInsightsFullAccess).

# Creating a custom IAM policy for Performance Insights


For users who don't have either the `AmazonRDSPerformanceInsightsReadOnly` or `AmazonRDSPerformanceInsightsFullAccess` policy, you can grant access to Performance Insights by creating or modifying a user-managed IAM policy. When you attach the policy to an IAM permission set or role, the recipient can use Performance Insights.

**To create a custom policy**

1. Open the IAM console at [https://console.amazonaws.cn/iam/](https://console.amazonaws.cn/iam/).

1. In the navigation pane, choose **Policies**.

1. Choose **Create policy**.

1. On the **Create Policy** page, choose the **JSON** option.

1. Copy and paste the text provided in the *JSON policy document* section in the *Amazon Managed Policy Reference Guide* for [https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonRDSPerformanceInsightsReadOnly.html](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonRDSPerformanceInsightsReadOnly.html) or [https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonRDSPerformanceInsightsFullAccess.html](https://docs.amazonaws.cn/aws-managed-policy/latest/reference/AmazonRDSPerformanceInsightsFullAccess.html) policy.

1. Choose **Review policy**.

1. Provide a name for the policy and optionally a description, and then choose **Create policy**.

You can now attach the policy to a permission set or role. The following procedure assumes that you already have a user available for this purpose.

**To attach the policy to a user**

1. Open the IAM console at [https://console.amazonaws.cn/iam/](https://console.amazonaws.cn/iam/).

1. In the navigation pane, choose **Users**.

1. Choose an existing user from the list.
**Important**  
To use Performance Insights, make sure that you have access to Amazon RDS in addition to the custom policy. For example, the `AmazonRDSPerformanceInsightsReadOnly` predefined policy provides read-only access to Amazon RDS. For more information, see [Managing access using policies](UsingWithRDS.IAM.md#security_iam_access-manage).

1. On the **Summary** page, choose **Add permissions**.

1. Choose **Attach existing policies directly**. For **Search**, type the first few characters of your policy name, as shown in the following image.   
![\[Choose a Policy\]](http://docs.amazonaws.cn/en_us/AmazonRDS/latest/AuroraUserGuide/images/perf_insights_attach_iam_policy.png)

1. Choose your policy, and then choose **Next: Review**.

1. Choose **Add permissions**.

# Changing an Amazon KMS policy for Performance Insights


Performance Insights uses an Amazon KMS key to encrypt sensitive data. When you enable Performance Insights through the API or the console, you can do either of the following:
+ Choose the default Amazon managed key.

  Amazon RDS uses the Amazon managed key for your new DB instance. Amazon RDS creates an Amazon managed key for your Amazon Web Services account. Your Amazon Web Services account has a different Amazon managed key for Amazon RDS for each Amazon Web Services Region.
+ Choose a customer managed key.

  If you specify a customer managed key, users in your account that call the Performance Insights API need the `kms:Decrypt` and `kms:GenerateDataKey` permissions on the KMS key. You can configure these permissions through IAM policies. However, we recommend that you manage these permissions through your KMS key policy. For more information, see [Key policies in Amazon KMS](https://docs.amazonaws.cn/kms/latest/developerguide/key-policies.html) in the *Amazon Key Management Service Developer Guide*. 

**Example**  
The following example shows how to add statements to your KMS key policy. These statements allow access to Performance Insights. Depending on how you use the KMS key, you might want to change some restrictions. Before adding statements to your policy, remove all comments.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Id" : "your-policy",
    "Statement" : [ 
        {
            "Sid" : "AllowViewingRDSPerformanceInsights",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws-cn:iam::444455556666:role/Role1"
                ]
                },
             "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
                ],
            "Resource": "*",
            "Condition" : {
            "StringEquals" : {
                "kms:ViaService" : "rds.us-east-1.amazonaws.com"
                },
            "ForAnyValue:StringEquals": {
                "kms:EncryptionContext:aws:pi:service": "rds",
                "kms:EncryptionContext:service": "pi",
                "kms:EncryptionContext:aws:rds:db-id": "db-AAAAABBBBBCCCCDDDDDEEEEE"
                }
            }
        }
    ]
}
```

## How Performance Insights uses Amazon KMS customer managed key


Performance Insights uses customer managed keys to encrypt sensitive data. When you turn on Performance Insights, you can provide an Amazon KMS key through the API. Performance Insights creates Amazon KMS permissions on this key. It uses the key and performs the necessary operations to process sensitive data. Sensitive data includes fields such as user, database, application, and SQL query text. Performance Insights ensures that the data remains encrypted both at rest and in-flight.

## How Performance Insights IAM works with Amazon KMS


IAM gives permissions to specific APIs. Performance Insights has the following public APIs, which you can restrict using IAM policies:
+ `DescribeDimensionKeys`
+ `GetDimensionKeyDetails`
+ `GetResourceMetadata`
+ `GetResourceMetrics`
+ `ListAvailableResourceDimensions`
+ `ListAvailableResourceMetrics`

You can use the following API requests to get sensitive data.
+ `DescribeDimensionKeys`
+ `GetDimensionKeyDetails`
+ `GetResourceMetrics`

When you use the API to get sensitive data, Performance Insights leverages the caller's credentials. This check ensures that access to sensitive data is limited to those with access to the KMS key.

When calling these APIs, you need permissions to call the API through the IAM policy and permissions to invoke the `kms:decrypt` action through the Amazon KMS key policy.

The `GetResourceMetrics` API can return both sensitive and non-sensitive data. The request parameters determine whether the response should include sensitive data. The API returns sensitive data when the request includes a sensitive dimension in either the filter or group-by parameters. 

For more information about the dimensions that you can use with the `GetResourceMetrics` API, see [DimensionGroup](https://docs.amazonaws.cn/performance-insights/latest/APIReference/API_DimensionGroup.html).

**Examples**  
The following example requests the sensitive data for the `db.user` group:  

```
POST / HTTP/1.1
Host: <Hostname>
Accept-Encoding: identity
X-Amz-Target: PerformanceInsightsv20180227.GetResourceMetrics
Content-Type: application/x-amz-json-1.1
User-Agent: <UserAgentString>
X-Amz-Date: <Date> 
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>
{
  "ServiceType": "RDS",
  "Identifier": "db-ABC1DEFGHIJKL2MNOPQRSTUV3W",
  "MetricQueries": [
    {
      "Metric": "db.load.avg",
      "GroupBy": {
        "Group": "db.user",
        "Limit": 2
      }
    }
  ],
  "StartTime": 1693872000,
  "EndTime": 1694044800,
  "PeriodInSeconds": 86400
}
```

**Example**  
The following example requests the non-sensitive data for the `db.load.avg` metric:  

```
POST / HTTP/1.1
Host: <Hostname>
Accept-Encoding: identity
X-Amz-Target: PerformanceInsightsv20180227.GetResourceMetrics
Content-Type: application/x-amz-json-1.1
User-Agent: <UserAgentString>
X-Amz-Date: <Date> 
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
Content-Length: <PayloadSizeBytes>
{
    "ServiceType": "RDS",
    "Identifier": "db-ABC1DEFGHIJKL2MNOPQRSTUV3W",
    "MetricQueries": [
        {
            "Metric": "db.load.avg"
        }
    ],
    "StartTime": 1693872000,
    "EndTime": 1694044800,
    "PeriodInSeconds": 86400
}
```

# Granting fine-grained access for Performance Insights


Fine-grained access control offers additional ways of controlling access to Performance Insights. This access control can allow or deny access to individual dimensions for `GetResourceMetrics`, `DescribeDimensionKeys`, and `GetDimensionKeyDetails` Performance Insights actions. To use fine-grained access, specify dimensions in the IAM policy by using condition keys. The evaluation of the access follows the IAM policy evaluation logic. For more information, see [Policy evaluation logic](https://docs.amazonaws.cn/IAM/latest/UserGuide/reference_policies_evaluation-logic.html) in the *IAM User Guide*. If the IAM policy statement doesn't specify any dimension, then the statement controls access to all the dimensions for the specified action. For the list of available dimensions, see [https://docs.amazonaws.cn/performance-insights/latest/APIReference/API_DimensionGroup.html](https://docs.amazonaws.cn/performance-insights/latest/APIReference/API_DimensionGroup.html).

To find out the dimensions that your credentials are authorized to access, use the `AuthorizedActions` parameter in `ListAvailableResourceDimensions` and specify the action. The allowed values for `AuthorizedActions` are as follows:
+ `GetResourceMetrics`
+ `DescribeDimensionKeys`
+ `GetDimensionKeyDetails`

For example, if you specify `GetResourceMetrics` to the `AuthorizedActions` parameter, `ListAvailableResourceDimensions` returns the list of dimensions that the `GetResourceMetrics` action is authorized to access. If you specify multiple actions in the `AuthorizedActions` parameter, then `ListAvailableResourceDimensions` returns an intersection of dimensions that those actions are authorized to access.

**Example**  
The following example provides access to the specified dimensions for `GetResourceMetrics` and `DescribeDimensionKeys` actions.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "AllowToDiscoverDimensions",
            "Effect": "Allow",
            "Action": [
                "pi:ListAvailableResourceDimensions"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ]
        },
        {
            "Sid": "SingleAllow",
            "Effect": "Allow",
            "Action": [
                "pi:GetResourceMetrics",
                "pi:DescribeDimensionKeys"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ],
            "Condition": {
                "ForAllValues:StringEquals": {
                    "pi:Dimensions": [
                        "db.sql_tokenized.id",
                        "db.sql_tokenized.statement"
                    ]
                }
            }
        }
        

    ]
}
```
The following is the response for the requested dimension:  

```
	// ListAvailableResourceDimensions API
// Request
{
    "ServiceType": "RDS",
    "Identifier": "db-ABC1DEFGHIJKL2MNOPQRSTUV3W",
    "Metrics": [ "db.load" ],
    "AuthorizedActions": ["DescribeDimensionKeys"]
}

// Response
{    
    "MetricDimensions": [ {
        "Metric": "db.load",
        "Groups": [
            {
                "Group": "db.sql_tokenized",
                "Dimensions": [
                    { "Identifier": "db.sql_tokenized.id" },
                  //  { "Identifier": "db.sql_tokenized.db_id" }, // not included because not allows in the IAM Policy
                    { "Identifier": "db.sql_tokenized.statement" }
                ] 
            }
            
        ] }
    ]
}
```
The following example specifies one allow and two deny access for the dimensions.    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
          {
            "Sid": "AllowToDiscoverDimensions",
            "Effect": "Allow",
            "Action": [
                "pi:ListAvailableResourceDimensions"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ]
          },

          {
            "Sid": "O01AllowAllWithoutSpecifyingDimensions",
            "Effect": "Allow",
            "Action": [
                "pi:GetResourceMetrics",
                "pi:DescribeDimensionKeys"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ]
        },
        
        {
            "Sid": "O01DenyAppDimensionForAll",
            "Effect": "Deny",
            "Action": [
                "pi:GetResourceMetrics",
                "pi:DescribeDimensionKeys"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ],
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "pi:Dimensions": [
                        "db.application.name"
                    ]
                }
            }
        },
        
        {
            "Sid": "O01DenySQLForGetResourceMetrics",
            "Effect": "Deny",
            "Action": [
                "pi:GetResourceMetrics"
            ],
            "Resource": [
                "arn:aws-cn:pi:us-east-1:123456789012:metrics/rds/db-ABC1DEFGHIJKL2MNOPQRSTUV3W"
            ],
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "pi:Dimensions": [
                        "db.sql_tokenized.statement"
                    ]
                }
            }
        }
    ]
}
```
The following are the responses for the requested dimensions:  

```
			// ListAvailableResourceDimensions API
// Request
{
    "ServiceType": "RDS",
    "Identifier": "db-ABC1DEFGHIJKL2MNOPQRSTUV3W",
    "Metrics": [ "db.load" ],
    "AuthorizedActions": ["GetResourceMetrics"]
}

// Response
{    
    "MetricDimensions": [ {
        "Metric": "db.load",
        "Groups": [
            {
                "Group": "db.application",
                "Dimensions": [
                
                  // removed from response because denied by the IAM Policy
                  //  { "Identifier": "db.application.name" }  
                ]
            },
            {
                "Group": "db.sql_tokenized",
                "Dimensions": [
                    { "Identifier": "db.sql_tokenized.id" },
                    { "Identifier": "db.sql_tokenized.db_id" },
                    
                  // removed from response because denied by the IAM Policy
                  //  { "Identifier": "db.sql_tokenized.statement" }
                ] 
            },
            ...
        ] }
    ]
}
```

```
// ListAvailableResourceDimensions API
// Request
{
    "ServiceType": "RDS",
    "Identifier": "db-ABC1DEFGHIJKL2MNOPQRSTUV3W",
    "Metrics": [ "db.load" ],
    "AuthorizedActions": ["DescribeDimensionKeys"]
}

// Response
{    
    "MetricDimensions": [ {
        "Metric": "db.load",
        "Groups": [
            {
                "Group": "db.application",
                "Dimensions": [
                  // removed from response because denied by the IAM Policy
                  //  { "Identifier": "db.application.name" }  
                ]
            },
            {
                "Group": "db.sql_tokenized",
                "Dimensions": [
                    { "Identifier": "db.sql_tokenized.id" },
                    { "Identifier": "db.sql_tokenized.db_id" },
                    
                  // allowed for DescribeDimensionKeys because our IAM Policy 
                  // denies it only for GetResourceMetrics
                    { "Identifier": "db.sql_tokenized.statement" }
                ] 
            },
            ...
        ] }
    ]
}
```

# Using tag-based access control for Performance Insights


You can control access to Performance Insights metrics using tags inherited from the parent DB instance. To control access to Performance Insights operations, use IAM policies. These policies can check the tags on your DB instance to determine permissions.

## How tags work with Performance Insights


Performance Insights automatically applies your DB instance tags to authorize Performance Insights metrics. When you add tags to your DB instance, you can immediately use those tags to control access to Performance Insights data.
+ To add or update tags for Performance Insights metrics, modify the tags on your DB instance.
+ To view tags for Performance Insights metrics, call `ListTagsForResource` on the Performance Insights metric resource. It will return the tags from the DB instance associated with the metric.

**Note**  
The `TagResource` and `UntagResource` operations return an error if you try to use them directly on Performance Insights metrics.

## Creating tag-based IAM policies


To control access to Performance Insights operations, use the `aws:ResourceTag` condition key in your IAM policies. These policies check the tags on yourDB instance.

**Example**  
This policy prevents access to Performance Insights metrics for production databases. The policy denies the `pi:GetResourceMetrics` operation in Performance Insights for any database resource tagged with `env:prod`.   

```
 {
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Deny",
            "Action": "pi:GetResourceMetrics",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:ResourceTag/env": "prod"
                }
            }
        }
    ]
}
```