Using Amazon Secrets Manager secrets instead of database credentials in Amazon QuickSight - Amazon QuickSight
Granting QuickSight access to Secrets Manager and selected secretsCreating or updating a data source with secret credentials using the QuickSight APIWhat's in the secretModifying the secret
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon Secrets Manager secrets instead of database credentials in Amazon QuickSight

   Intended audience: Amazon QuickSight Administrators and Amazon QuickSight developers 

Amazon Secrets Manager is a secret storage service that you can use to protect database credentials, API keys, and other secret information. Using a key helps you ensure that the secret can't be compromised by someone examining your code, because the secret isn't stored in the code. For an overview, see the Amazon Secrets Manager User Guide.

Amazon QuickSight administrators can grant QuickSight read-only access to secrets they create in Secrets Manager. These secrets can be used in place of database credentials when creating and editing data sources using the QuickSight API.

QuickSight supports using secrets with data source types that support credential pair authentication. Jira and ServiceNow are not currently supported.

Note

If you use Amazon Secrets Manager with Amazon QuickSight, you are billed for access and maintenance as described in the Amazon Secrets Manager Pricing page. In your billing statement, the costs are itemized under Secrets Manager and not under QuickSight.

Use the following procedures described in the following sections to integrate Secrets Manager with Amazon QuickSight.

Granting QuickSight access to Secrets Manager and selected secrets

If you're an administrator and you have secrets in Secrets Manager, you can grant Amazon QuickSight read-only access to selected secrets.

To grant QuickSight access to Secrets Manager and selected secrets

  1. In QuickSight, choose your user icon on the upper right, and then choose Manage QuickSight.

    Manage QuickSight menu.

  2. Choose Security & permissions on the left.

  3. Choose Manage in QuickSight access to Amazon resources.

    Manage security and permissions.

  4. In Allow access and autodiscovery for these resources, choose Amazon Secrets Manager, Select secrets.

    The Amazon Secrets Manager secrets page opens.

  5. Select the secrets that you want to grant QuickSight read-only access to.

    Secrets in your QuickSight sign-up Region are shown automatically. To select secrets outside your home Region, choose Secrets in Other Amazon Regions, and then enter the Amazon Resource Names (ARNs) for those secrets.

  6. When you're done, choose Finish.

    QuickSight creates an IAM role called aws-quicksight-secretsmanager-role-v0 in your account. It grants users in the account read-only access to the specified secrets and looks similar to the following:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws-cn:secretsmanager:region:accountId:secret:secret_name"
      ]
    }
  ]
}

    When QuickSight users create analyses from or view dashboards that use a data source with secrets, QuickSight assumes this Secrets Manager IAM role. For more information about secret permissions policies, see Authentication and access control for Amazon Secrets Manager in the Amazon Secrets Manager User Guide.

    The specified secret in the QuickSight IAM role may have an additional resource policy that denies access. For more information, see Attach a permissions policy to a secret in the Amazon Secrets Manager User Guide.

    If you're using an Amazon managed Amazon KMS key to encrypt your secret, QuickSight doesn't require any additional permissions setup in Secrets Manager.

    If you're using a customer managed key to encrypt your secret, ensure that the QuickSight IAM role, aws-quicksight-secretsmanager-role-v0 has kms:Decrypt permissions. For more information, see Permissions for the KMS key in the Amazon Secrets Manager User Guide.

    For more information about the types of keys used in Amazon Key Management Service, see Customer keys and Amazon keys in the Amazon Key Management Service guide.

Creating or updating a data source with secret credentials using the QuickSight API

After the QuickSight administrator has granted QuickSight read-only access to Secrets Manager, you can create and update data sources in the API using a secret the administrator selected as credentials.

Following is an example API call to create a data source in QuickSight. This example uses the create-data-source API operation. You can also use the update-data-source operation. For more information, see CreateDataSource and UpdateDataSource in the Amazon QuickSight API Reference.

The user specified in the permissions in the following API call example can delete, view, and edit data sources for the specified MySQL data source in QuickSight. They can also view and update the data source permissions. Instead of a QuickSight username and password, a secret ARN is used as credentials for the data source.

aws quicksight create-data-source 
    --aws-account-id AWSACCOUNTID \ 
    --data-source-id DATASOURCEID \
    --name NAME \
    --type MYSQL \
    --permissions '[{"Principal": "arn:aws-cn:quicksight:region:accountID:user/namespace/username", "Actions": ["quicksight:DeleteDataSource", "quicksight:DescribeDataSource", "quicksight:DescribeDataSourcePermissions", "quicksight:PassDataSource", "quicksight:UpdateDataSource", "quicksight:UpdateDataSourcePermissions"]}]' \
    --data-source-parameters='{"MySQLParameters":{"Database": "database", "Host":"hostURL", "Port":"port"}}' \
    --credentials='{"SecretArn":"arn:aws-cn:secretsmanager:region:accountID:secret:secretname"}' \
    --region us-west-2

In this call, QuickSight authorizes secretsmanager:GetSecretValue access to the secret based on the API caller's IAM policy, not the IAM service role's policy. The IAM service role acts on the account level and is used when an analysis or dashboard is viewed by a user. It cannot be used to authorize secret access when a user creates or updates the data source.

When they edit a data source in the QuickSight UI, users can view the secret ARN for data sources that use Amazon Secrets Manager as the credential type. However, they can't edit the secret, or select a different secret. If they need to make changes, for example to the database server or port, users first need to choose Credential pair and enter their QuickSight account username and password.

Secrets are automatically removed from a data source when the data source is altered in the UI. To restore the secret to the data source, use the update-data-source API operation.

What's in the secret

QuickSight requires the following JSON format to access your secret:

{
  "username": "username",
  "password": "password"
}

The username and password fields are required for QuickSight to access secrets. All other fields are optional and are ignored by QuickSight.

The JSON format may vary depending on the type of database. For more information, see JSON structure of Amazon Secrets Manager database credential secrets in the Amazon Secrets Manager User Guide.

Modifying the secret

To modify a secret, you use Secrets Manager. After you make changes to a secret, the updates become available the next time QuickSight requests access to the secret.