--- title: "Configure an AWS Secrets Manager keeper | Grafana Cloud documentation" description: "Configure an AWS Secrets Manager keeper to store and manage sensitive values outside of Grafana using your own AWS account." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Configure an AWS Secrets Manager keeper You can configure an AWS Secrets Manager keeper to store and manage sensitive values outside of Grafana using your own AWS infrastructure. Grafana connects to your AWS Secrets Manager using cross-account role assumption through AWS Security Token Service (STS). Grafana never stores your AWS credentials. You create an IAM role in your AWS account, and Grafana assumes that role to read and write secrets on your behalf. [](/media/secrets-management/IAM_assume_role.png) ## Before you begin To configure an AWS Secrets Manager keeper, you need: - A Grafana Cloud account with Admin permissions. - An AWS account with permissions to create IAM roles and policies. - AWS Secrets Manager enabled in your target region. ## Set up AWS IAM Configure an IAM policy and role in your AWS account so Grafana can access your Secrets Manager. ### Create the permissions policy Create an IAM policy that defines which Secrets Manager actions Grafana can perform. To create the permissions policy, follow these steps: 1. Sign in to the [AWS IAM Console](https://console.aws.amazon.com/iam/). 2. In the navigation pane, choose **Policies**, then **Create policy**. 3. Select the **JSON** tab. 4. Paste the following policy: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "GrafanaManagedSecrets", "Effect": "Allow", "Action": [ "secretsmanager:CreateSecret", "secretsmanager:UpdateSecret", "secretsmanager:PutSecretValue", "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret", "secretsmanager:DeleteSecret", "secretsmanager:TagResource" ], "Resource": "arn:aws:secretsmanager:*:*:secret:grafana-secrets-manager/*" }, { "Sid": "ListSecretsForValidation", "Effect": "Allow", "Action": ["secretsmanager:ListSecrets"], "Resource": "*" }, { "Sid": "ReadExistingSecrets", "Effect": "Allow", "Action": ["secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue"], "Resource": "*" } ] } ``` 5. Click **Next**. 6. Name the policy `GrafanaSecretsManagerPolicy`. 7. Click **Create policy**. The following table describes the purpose of each statement in the policy: Expand table | Statement | Purpose | |----------------------------|------------------------------------------------------------------------------------------| | `GrafanaManagedSecrets` | Allows Grafana to create, read, update, delete, and tag secrets in your Secrets Manager. | | `ListSecretsForValidation` | Allows Grafana to list secrets when validating references. | | `ReadExistingSecrets` | Allows Grafana to read any existing secret you reference. You can restrict this further. | #### Restrict access to specific secrets By default, the `ReadExistingSecrets` statement grants Grafana access to all secrets in your account. To limit access, replace the statement with a resource-scoped policy. To restrict by Amazon Resource Name (ARN), use the following policy: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "Sid": "ReadExistingSecrets", "Effect": "Allow", "Action": ["secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue"], "Resource": [ "arn:aws:secretsmanager:::secret:-*", "arn:aws:secretsmanager:::secret:-*" ] } ``` Alternatively, use tag-based access control: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "Sid": "ReadExistingSecrets", "Effect": "Allow", "Action": ["secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue"], "Resource": "*", "Condition": { "StringEquals": { "aws:ResourceTag/grafana-accessible": "true" } } } ``` #### Restrict Grafana to read-only access If you want to manage all secret creation directly in AWS and only allow Grafana to read existing secrets, remove the `GrafanaManagedSecrets` statement from the permissions policy entirely. Use only the `ReadExistingSecrets` and `ListSecretsForValidation` statements: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "ListSecretsForValidation", "Effect": "Allow", "Action": ["secretsmanager:ListSecrets"], "Resource": "*" }, { "Sid": "ReadExistingSecrets", "Effect": "Allow", "Action": ["secretsmanager:DescribeSecret", "secretsmanager:GetSecretValue"], "Resource": "*" } ] } ``` With this policy, Grafana users can only create [reference-based secure values](#create-a-reference-based-secret) that point to existing secrets in AWS. Any attempt to create a value-based secure value fails because the IAM role doesn’t have permission to create secrets in AWS Secrets Manager. This approach is useful when you want to: - Maintain full control over secret creation and lifecycle in AWS. - Use your existing AWS processes for provisioning and rotating secrets. - Limit Grafana to a read-only consumer of secrets you manage. ### Create the IAM role After you create the permissions policy, create an IAM role in the same AWS account. Grafana assumes this role to access your Secrets Manager. To create the IAM role, follow these steps: 01. In the IAM Console navigation pane, choose **Roles**, then **Create role**. 02. For **Trusted entity type**, select **AWS account**. 03. Select **Another AWS account**. 04. Enter the Grafana Account ID: `008923505280`. 05. Check **Require external ID**. 06. Enter an external ID value of your choice. This value prevents [confused deputy attacks](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html#id_roles_third-party_external-id). Keep it confidential and don’t share it in public repositories or logs. This is recommended if you don’t own or have administrative access to the account that can assume this role. 07. Click **Next**. 08. Search for and select `GrafanaSecretsManagerPolicy`. 09. Click **Next**. 10. Enter the role name: `grafana-secrets-manager`. > Caution > > The role must be named `grafana-secrets-manager`. The Grafana AWS account is configured to only assume a role with this name. 11. Click **Create role**. #### Verify the trust policy After you create the role, verify that the trust policy is configured correctly. 1. Open the newly created role in the IAM Console. 2. Select the **Trust relationships** tab. 3. Verify the policy includes the Grafana Account ID in the Principal and the correct external ID in the Condition: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::008923505280:user/grafana-secrets-manager" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "sts:ExternalId": "" } } } ] } ``` 4. Copy the **Role ARN** from the **Summary** section. You need this value when you configure the keeper in Grafana. ## Configure the keeper in Grafana After you create the IAM role in AWS, configure and activate the keeper in Grafana. To configure the keeper, follow these steps: 1. Go to **Administration** > **Secrets Management** > **Keepers**. 2. Click **Add keeper**. 3. Click **AWS Secrets Manager**. 4. Click **Configure Keeper** to expand the section. 5. Enter the required configuration fields. ### Configuration reference The following table describes the general keeper fields: Expand table | Field | Required | Description | |-----------------|----------|----------------------------------------| | **Name** | Yes | A unique name to identify this keeper. | | **Description** | Yes | A description of the keeper’s purpose. | The following table describes the AWS configuration fields: Expand table | Field | Type | Description | |-----------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Region** | String | The AWS region where your secrets are stored. Required. Grafana supports any region where AWS Secrets Manager is available. For a list of supported regions, refer to [AWS Secrets Manager endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/asm.html). | | **Role ARN** | String | The Amazon Resource Name (ARN) of the IAM role that Grafana assumes to access your AWS account. Required. | | **External ID** | String | The external ID used to prevent confused deputy attacks. This value must match the external ID in your IAM role trust policy on the `"sts:ExternalId"` line. Required. | ### Activate the keeper Creating a keeper registers the configuration but doesn’t start using it. To start storing secrets in AWS Secrets Manager, you need to activate the keeper: 1. Go to **Administration** > **Secrets Management** > **Keepers**. 2. Click **Activate** next to the keeper you created. ## Create secrets After your keeper is configured and activated, you can create secrets in two ways: by storing a new value or by referencing an existing secret in AWS. Grafana retrieves secret values from AWS Secrets Manager as-is. It doesn’t parse, unpack, or extract fields from the value. If your secret is a JSON object, Grafana returns the entire JSON string rather than a specific key within it. Store each secret as a plain string containing only the value Grafana needs. ### Create a value-based secret A value-based secret stores a new secret value in AWS Secrets Manager. To create a value-based secret, follow these steps: 1. Go to **Administration** > **Secrets Management** > **Values**. 2. Click **Create secure value**. 3. In the **Create secret** dialog box, enter the **Name** and **Description**. 4. For **Secret type**, leave **Store a new value** selected. 5. In **Value**, enter the secret value. 6. Optionally, select **Decrypters** and add **Labels**. 7. Click **Create**. The **Value** field is write-only and is never returned in read or list responses. The Decrypters field controls which Grafana services can decrypt the secret. Grafana creates the secret in AWS Secrets Manager with the following naming pattern: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none grafana-secrets-manager/// ``` For example, a secure value named `db-password` with namespace `stacks-12345` at version `1` becomes: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none grafana-secrets-manager/stacks-12345/db-password/1 ``` The namespace value depends on your Grafana instance deployment. Grafana also tags each secret with `namespace`, `name`, `managedBy`, and `version` metadata. ### Create a reference-based secret A reference-based secret points to an existing secret in AWS Secrets Manager without creating or modifying it. The **Secret type** options appear in the create form only when an AWS Secrets Manager keeper is active. To create a reference-based secret, follow these steps: 1. Go to **Administration** > **Secrets Management** > **Values**. 2. Click **Create secure value**. 3. In the **Create secret** dialog box, enter the **Name** and **Description**. 4. For **Secret type**, select **Reference existing secret**. The **Value** field is replaced by **AWS secret name or ARN**. 5. In **AWS secret name or ARN**, enter the AWS secret name or the full Amazon Resource Name (ARN). 6. Optionally, select **Decrypters** and add **Labels**. 7. Click **Create**. You can reference an existing secret using either the AWS secret name, for example, `grafana-secrets-manager/stacks-023456/api-token/1`, or the full ARN, for example, `arn:aws:secretsmanager:eu-central-1:123456789012:secret:grafana-secrets-manager/stacks-023456/api-token/1-GR1SI2`. > Note > > Reference-based secrets don’t create or modify secrets in AWS. They only store a pointer to an existing secret. For reference-based secrets, you can continue to use your standard AWS secret rotation methods, such as [automatic rotation with AWS Lambda](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html). Because Grafana reads the secret value from AWS at access time, rotated values are automatically reflected without any changes in Grafana. ### Understand deletion behavior The behavior when you delete a secure value depends on the type of secret: - **Value-based secrets:** The secret is permanently deleted from AWS Secrets Manager immediately. There is no recovery window. - **Reference-based secrets:** Only the reference in Grafana is deleted. The AWS secret isn’t affected. ## Permissions The following table describes the RBAC permissions for keepers: Expand table | Permission | Description | |--------------------------------------------------|-----------------------| | `secret.keepers:read` or `secret.keepers:create` | View the keepers page | | `secret.keepers:read` | List keepers | | `secret.keepers:create` | Create a keeper | | `secret.keepers:write` | Edit a keeper | | `secret.keepers:delete` | Delete a keeper | Grafana includes two fixed roles for keepers: Expand table | Fixed role | Description | Included permissions | |-------------------------------|-------------------------------------|-------------------------------------------------------------------------------------------------| | `fixed:secret.keepers:reader` | Read and list keepers. | `secret.keepers:read` | | `fixed:secret.keepers:writer` | Create, update, and delete keepers. | `secret.keepers:create`, `secret.keepers:read`, `secret.keepers:write`, `secret.keepers:delete` | Permissions are managed through Grafana role-based access control (RBAC). For more information, refer to [Role-based access control](/docs/grafana-cloud/platform/security-and-account-management/security-and-access/authentication-and-permissions/access-control/). ## Security best practices Follow these practices to secure your AWS Secrets Manager integration. ### Use the external ID The external ID prevents confused deputy attacks where a malicious actor could trick Grafana into accessing your AWS resources on their behalf. Always set an external ID when you create the IAM role, and keep it confidential. Don’t share it in public repositories or logs, and use a unique value for each integration. ### Apply least privilege - Scope the `ReadExistingSecrets` statement to only the secrets Grafana needs. - Use separate IAM roles for different Grafana environments, for example, development, staging, and production. - Regularly audit which secrets Grafana accesses using AWS CloudTrail. ### Enable AWS CloudTrail logging To monitor all Secrets Manager API calls, follow these steps: 1. Enable CloudTrail in your AWS account. 2. Filter events by `eventSource: secretsmanager.amazonaws.com`. 3. Set up alerts for unexpected access patterns. ## Related resources - [Manage secrets](/docs/grafana-cloud/platform/security-and-account-management/security-and-access/manage-secrets/) - [Troubleshoot an AWS Secrets Manager keeper](/docs/grafana-cloud/platform/security-and-account-management/security-and-access/manage-secrets/troubleshoot-aws-secrets-manager-keeper/) - [AWS Secrets Manager documentation](https://docs.aws.amazon.com/secretsmanager/) - [AWS IAM roles for cross-account access](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)