AWS aurora-dsql documentation change
Summary
Expanded authentication token generation documentation with detailed instructions for AWS Console, CloudShell, CLI, and multiple SDKs (Python/C++/JavaScript/Java/Rust/Ruby/.NET/Golang). Added code samples and removed links to external implementation guides.
Security assessment
The changes improve documentation for secure authentication token generation practices but don't address a specific vulnerability. Added emphasis on IAM permissions, token expiration defaults (15m-1hr CLI vs console differences), and role-based access controls enhances security awareness.
Diff
diff --git a/aurora-dsql/latest/userguide/SECTION_authentication-token.md b/aurora-dsql/latest/userguide/SECTION_authentication-token.md index 9cb061281..2d05fb261 100644 --- a//aurora-dsql/latest/userguide/SECTION_authentication-token.md +++ b//aurora-dsql/latest/userguide/SECTION_authentication-token.md @@ -4,0 +5,2 @@ +ConsoleAWS CloudShellAWS CLIAurora DSQL SDKs + @@ -9 +11 @@ Amazon Aurora DSQL is provided as a Preview service. To learn more, see [Betas a -To connect to Amazon Aurora DSQL with your preferred SQL client, you must generate an authentication token that you use as the password. By default, these tokens automatically expire in one hour if you use the AWS console to create it. If you use the AWS CLI or SDKs to create the token, the default is 15 minutes. The maximum is 604,800 seconds, which is one week. To connect to Aurora DSQL from your client again, you can use the same token if it hasn't expired, or you can generate a new one. +To connect to Amazon Aurora DSQL with a SQL client, generate an authentication token to use as the password. If you create the token using the AWS console, these tokens automatically expire in one hour by default. If you use the AWS CLI or SDKs to create the token, the default is 15 minutes. The maximum is 604,800 seconds, which is one week. To connect to Aurora DSQL from your client again, you can use the same token if it hasn't expired, or you can generate a new one. @@ -11 +13 @@ To connect to Amazon Aurora DSQL with your preferred SQL client, you must genera -To get started with generating a token, first [create an IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) and [a cluster in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html#getting-started-quickstart), and then use the console, AWS CLI, or the AWS SDKs to generate a token. +To get started with generating a token, [create an IAM policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) and [a cluster in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html#getting-started-quickstart). Then use the console, AWS CLI, or the AWS SDKs to generate a token. @@ -13 +15 @@ To get started with generating a token, first [create an IAM policy](https://doc -At a minimum, you must have the following IAM permissions listed in <https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html#authentication-authorization-iam-role-connect>, depending on what database role you want to use to connect. +At a minimum, you must have the IAM permissions listed in [Connecting to your cluster using IAM](./authentication-authorization.html#authentication-authorization-iam-role-connect), depending on which database role you use to connect. @@ -17 +19,374 @@ At a minimum, you must have the following IAM permissions listed in <https://doc - * [Use the AWS console to generate a token in Aurora DSQL](./authentication-token-console.html) + * Use the AWS console to generate a token in Aurora DSQL + + * Use AWS CloudShell to generate a token in Aurora DSQL + + * Use the AWS CLI to generate a token in Aurora DSQL + + * Use the SDKs to generate a token in Aurora DSQL + + + + +## Use the AWS console to generate a token in Aurora DSQL + +Aurora DSQL authenticates users with a token rather than a password. You can generate the token from the console. + +###### To generate an authentication token + + 1. Sign in to the AWS Management Console and open the Aurora DSQL console at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). + + 2. Create a cluster using the steps in [Step 1: Create an Aurora DSQL single-Region cluster](./getting-started.html#getting-started-create-cluster) or [Step 4: Create a multi-Region linked cluster](./getting-started.html#getting-started-multi-region). + + 3. After you create a cluster, choose the cluster ID of the cluster for which you want to generate an authentication token. + + 4. Choose **Connect**. + + 5. In the modal, choose whether you want to connect as `admin` or with a [custom database role](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/authentication-authorization.html#authentication-authorization-iam-role-connect). + + 6. Copy the generated authentication token and use it to connect to [ Aurora DSQL from your SQL client](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/accessing-sql-clients.html). + + + + +To learn more about custom database roles and IAM in Aurora DSQL, see [Authentication and authorization for Aurora DSQL](./authentication-authorization.html). + +## Use AWS CloudShell to generate a token in Aurora DSQL + +Before you can generate an authentication token using AWS CloudShell, make sure that you have completed the following prerequisites: + + * [Created a Aurora DSQL cluster](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/getting-started.html#getting-started-quickstart) + + * Added permission to run the Amazon S3 operation `get-object` to retrieve objects from an AWS account outside of your organization + + + + +###### To generate an authentication token using AWS CloudShell + + 1. Sign in to the AWS Management Console and open the Aurora DSQL console at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). + + 2. At the bottom left of the AWS console, choose AWS CloudShell. + + 3. Follow [Installing or updating to the latest verison of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) to install the AWS CLI. + + sudo ./aws/install --update + + 4. Run the following command to generate an authentication token for the `admin` role. Replace `us-east-1` with your Region and `cluster_endpoint` with the endpoint of your own cluster. + +###### Note + +If you're not connecting as `admin`, use `generate-db-connect-auth-token` instead. + + aws dsql generate-db-connect-admin-auth-token \ + --expires-in 3600 \ + --region us-east-1 \ + --hostname cluster_endpoint + +If you run into issues, see [Troubleshoot IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html) and [How can I troubleshoot access denied or unauthorized operation errors with an IAM policy?](https://repost.aws/knowledge-center/troubleshoot-iam-policy-issues). + + 5. Use the following command to use `psql` to start a connection to your cluster. + + PGSSLMODE=require \ + psql --dbname postgres \ + --username admin \ + --host cluster_endpoint + + 6. You should see a prompt to provide a password. Copy the token that you generated, and make sure you don't include any additional spaces or characters. Paste it into the following prompt from `psql`. + + Password for user admin: + + 7. Press **Enter**. You should see a PostgreSQL prompt. + + postgres=> + +If you get an access denied error, make sure that your IAM identity has the `dsql:DbConnectAdmin` permission. If you have the permission and continue to get access deny errors, see [Troubleshoot IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/troubleshoot.html) and [How can I troubleshoot access denied or unauthorized operation errors with an IAM policy?](https://repost.aws/knowledge-center/troubleshoot-iam-policy-issues). + + + + +To learn more about custom database roles and IAM in Aurora DSQL, see [Authentication and authorization for Aurora DSQL](./authentication-authorization.html). + +## Use the AWS CLI to generate a token in Aurora DSQL + +When your cluster is `ACTIVE`, you can generate an authentication token. Use either of the following techniques: + + * If you are connecting with the `admin` role, use the `generate-db-connect-admin-auth-token` command. + + * If you are connecting with a custom database role, use the `generate-db-connect-auth-token` command. + + + + +The following example uses the following attributes to generate an authentication token for the `admin` role. + + * `your_cluster_endpoint` – The endpoint of the cluster. It follows the format ``your_cluster_identifier`.dsql.`region`.on.aws`, as in the example `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`. + + * `region` – The AWS Region, such as `us-east-2` or `us-east-1`. + + + + +The following examples set the expiration time for the token to expire in 3600 seconds (1 hour). + +Linux and macOS + + + + aws dsql generate-db-connect-admin-auth-token \ + --region region \ + --expires-in 3600 \ + --hostname your_cluster_endpoint + +Windows + + + + aws dsql generate-db-connect-admin-auth-token ^ + --region=region ^ + --expires-in=3600 ^ + --hostname=your_cluster_endpoint + +## Use the SDKs to generate a token in Aurora DSQL + +You can generate an authentication token for your cluster when it is in `ACTIVE` status. The SDK examples use the following attributes to generate an authentication token for the `admin` role: + + * `your_cluster_endpoint` (or `yourClusterEndpoint`) – The endpoint of your Aurora DSQL cluster. The naming format is ``your_cluster_identifier`.dsql.`region`.on.aws`, as in the example `01abc2ldefg3hijklmnopqurstu.dsql.us-east-1.on.aws`. + + * `region` (or `RegionEndpoint`) – The AWS Region in which your cluster is located, such as `us-east-2` or `us-east-1`. + + + + +Python SDK + + +You can generate the token in the following ways: + + * If you're connecting with the `admin` role, use `generate_db_connect_admin_auth_token`. + + * If you're connecting with a custom database role, use `generate_connect_auth_token`. + + + + + + def generate_token(your_cluster_endpoint, region): + client = boto3.client("dsql", region_name=region) + # use `generate_db_connect_auth_token` instead if you are _not_ connecting as admin. + token = client.generate_db_connect_admin_auth_token(your_cluster_endpoint, region) + print(token) + return token + +C++ SDK + + +You can generate the token in the following ways: + + * If you're connecting with the `admin` role, use `GenerateDBConnectAdminAuthToken`. + + * If you're connecting with a custom database role, use `GenerateDBConnectAuthToken`. + + + + + + #include <aws/core/Aws.h> + #include <aws/dsql/DSQLClient.h> + #include <iostream> + + using namespace Aws; + using namespace Aws::DSQL; + + std::string generateToken(String yourClusterEndpoint, String region) {