AWS aurora-dsql documentation change
Summary
Added detailed 'Accessing Aurora DSQL' section with authentication token usage, SSL enforcement, and SQL client configuration guidance
Security assessment
The changes add documentation about security features including IAM authentication tokens (temporary credentials), mandatory SSL connections (PGSSLMODE=require), and session expiration policies. However, there is no evidence this addresses a specific disclosed vulnerability.
Diff
diff --git a/aurora-dsql/latest/userguide/getting-started.md b/aurora-dsql/latest/userguide/getting-started.md index a2712159e..d01e4b4b8 100644 --- a//aurora-dsql/latest/userguide/getting-started.md +++ b//aurora-dsql/latest/userguide/getting-started.md @@ -5 +5 @@ -PrerequisitesCreate a single-Region clusterConnect to a clusterRun SQL commandsCreate a multi-Region cluster +PrerequisitesAccessing Aurora DSQLCreate a single-Region clusterConnect to a clusterRun SQL commandsCreate a multi-Region cluster @@ -16,0 +17,2 @@ In the following sections, you’ll learn how to create single-Region and multi- + * Accessing Aurora DSQL + @@ -49 +51,166 @@ If you use the AWS CLI in a different environment, make sure that you manually s - * If you intend to access Aurora DSQL using a GUI, use DBeaver or JetBrains DataGrip. For more information, see [Accessing Aurora DSQL with DBeaver](./accessing.html#accessing-sql-clients-dbeaver) and [Accessing Aurora DSQL with JetBrains DataGrip](./accessing.html#accessing-sql-clients-datagrip). + * If you intend to access Aurora DSQL using a GUI, use DBeaver or JetBrains DataGrip. For more information, see Accessing Aurora DSQL with DBeaver and Accessing Aurora DSQL with JetBrains DataGrip. + + + + +## Accessing Aurora DSQL + +You can access Aurora DSQL through the following techniques. To learn how to use the CLI, APIs, and SDKs, see [Accessing Amazon Aurora DSQL programmatically](./programming-with.html#accessing-programmatic). + +###### Topics + + * Accessing Aurora DSQL through the AWS Management Console + + * Accessing Aurora DSQL using SQL clients + + * Using the PostgreSQL protocol with Aurora DSQL + + + + +### Accessing Aurora DSQL through the AWS Management Console + +You can access the AWS Management Console for Aurora DSQL at [https://console.aws.amazon.com/dsql](https://console.aws.amazon.com/dsql). You can perform the following actions in the console: + +**Create a cluster** + + +You can create either a single-Region or a multi-Region cluster. + +**Connect to a cluster** + + +Choose an authentication option that aligns with the policy attached to your IAM identity. Copy the authentication token and provide it as the password when you connect to your cluster. When you connect as an administrator, the console creates the token with the IAM action `dsql:DbConnectAdmin`. When you connect using a custom database role, the console creates a token with the IAM action `dsql:DbConnect`. + +**Modify a cluster** + + +You can enable or disable deletion protection. You can't delete a cluster when deletion protection is enabled. + +**Delete a cluster** + + +You can't undo this action and you won't be able to retrieve any data. + +### Accessing Aurora DSQL using SQL clients + +Aurora DSQL uses the PostgreSQL protocol. Use your preferred interactive client by providing a signed IAM [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) as the password when connecting to your cluster. An authentication token is a unique string of characters that is generated dynamically. Authentication tokens are generated using AWS Signature Version 4. The token is only used for authentication and doesn't affect the connection after it is established. If you try to re-connect using an expired token, the connection request is denied. For more information, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html). + +###### Topics + + * Accessing Aurora DSQL with psql (PostgreSQL interactive terminal) + + * Accessing Aurora DSQL with DBeaver + + * Accessing Aurora DSQL with JetBrains DataGrip + + + + +#### Accessing Aurora DSQL with psql (PostgreSQL interactive terminal) + +The `psql` utility is a terminal-based front-end to PostgreSQL. It enables you to type in queries interactively, issue them to PostgreSQL, and see the query results. For more information about `psql`, see [https://www.postgresql.org/docs/current/app-psql.htm](https://www.postgresql.org/docs/current/app-psql.htm). To download the PostgreSQL-provided installers, see [PostgreSQL Downloads](https://www.postgresql.org/download/). + +If you already have the AWS CLI installed, use the following example to connect to your cluster. You can also use AWS CloudShell which comes with `psql` preinstalled, or, you can install `psql` directly. + + + # Aurora DSQL requires a valid IAM token as the password when connecting. + # Aurora DSQL provides tools for this and here we're using Python. + export PGPASSWORD=$(aws dsql generate-db-connect-admin-auth-token \ + --region us-east-1 \ + --expires-in 3600 \ + --hostname your_cluster_endpoint) + + # Aurora DSQL requires SSL and will reject your connection without it. + export PGSSLMODE=require + + # Connect with psql which will automatically use the values set in PGPASSWORD and PGSSLMODE. + # Quiet mode will suppress unnecessary warnings and chatty responses. Still outputs errors. + psql --quiet \ + --username admin \ + --dbname postgres \ + --host your_cluster_endpoint + +#### Accessing Aurora DSQL with DBeaver + +DBeaver is an open-source, GUI-based database tool. You can use it to connect to and manage your database. To download DBeaver, see the [download page](https://dbeaver.io/download/) on the DBeaver Community website. The following steps explain how to connect to your cluster using DBeaver. + +###### To set up a new Aurora DSQL connection in DBeaver + + 1. Choose **New Database Connection**. + + 2. In the **New Database Connection** window, choose PostgreSQL. + + 3. In the **Connection settings/Main** tab, choose **Connect by: Host** and enter the following information. + + 1. **Host** \- Use your cluster endpoint. + +**Database** \- Enter `postgres` + +**Authentication** \- Choose `Database Native` + +**Username** \- Enter `admin` + +**Password** \- Generate an [ authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html). Copy the generated token and use it as your password. + + 4. Ignore any warnings and paste your authentication token into the **DBeaver Password** field. + +###### Note + +You must set SSL mode in the client connections. Aurora DSQL supports `SSLMODE=require`. Aurora DSQL enforces SSL communication on the server side and rejects non-SSL connections. + + 5. You should be connected to your cluster and can start running SQL statements. + + + + +###### Important + +The administrative features provided by DBeaver for the PostgreSQL databases (such as **Session Manager** and **Lock Manager**) don't apply to a database, due to its unique architecture. While accessible, these screens don't provide reliable information on the database health or status. + +**Authentication credentials expiry** + +Established sessions will remain authenticated for a maximum of 1 hour or until an explicit disconnect or a client-side timeout takes place. If new connections need to be established, a valid Authentication token must be provided in the **Password** field of the **Connection settings**. Trying to open a new session (for example, to list new tables, or a new SQL console) will force a new authentication attempt. If the authentication token configured in the **Connection settings** is no longer valid, that new session will fail and all the previously opened sessions will get invalidated at that point in time too. Have this in mind when choosing the duration of your IAM authentication token with the `expires-in` option. + +#### Accessing Aurora DSQL with JetBrains DataGrip + +JetBrains DataGrip is a cross-platform IDE for working with SQL and databases, including PostgreSQL. DataGrip includes a robust GUI with an intelligent SQL editor. To download DataGrip, go to the [download page](https://www.jetbrains.com/datagrip/download) on the JetBrains website. + +###### To set up a new Aurora DSQL connection in JetBrains DataGrip + + 1. Choose **New Data Source** and choose PostgreSQL. + + 2. In the Data Sources/General tab, enter the following information: + + 1. **Host** \- Use your cluster endpoint. + +**Port** \- Aurora DSQL uses the PostgreSQL default: `5432` + +**Database** \- Aurora DSQL uses the PostgreSQL default of `postgres` + +**Authentication** \- Choose `User & Password `. + +**Username** \- Enter `admin`. + +**Password** \- [ Generate a token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html) and paste it into this field. + +**URL** \- Don't modify this field. It will be auto-populated based on the other fields. + + 3. **Password** \- Provide this by generating an authentication token. Copy the resulting output of the token generator and paste it into the password field. + +###### Note + +You must set SSL mode in the client connections. Aurora DSQL supports `PGSSLMODE=require`. Aurora DSQL enforces SSL communication on the server side and will reject non-SSL connections. + + 4. You should be connected to your cluster and can start running SQL statements: + + + + +###### Important + +Some views provided by DataGrip for the PostgreSQL databases (such as Sessions) don't apply to a database because of its unique architecture. While accessible, these screens don't provide reliable information on the actual sessions connected to the database. + +**Authentication credentials expiration** + +Established sessions remain authenticated for a maximum of 1 hour or until an explicit disconnect or a client-side timeout takes place. If new connections need to be established, a new Authentication token must be generated and provided in the **Password** field of the **Data Source Properties**. Trying to open a new session (for example, to list new tables, or a new SQL console) forces a new authentication attempt. If the authentication token configured in the **Connection** settings is no longer valid, that new session will fail and all previously opened sessions will become invalid. @@ -50,0 +218 @@ If you use the AWS CLI in a different environment, make sure that you manually s +### Using the PostgreSQL protocol with Aurora DSQL @@ -51,0 +220 @@ If you use the AWS CLI in a different environment, make sure that you manually s +PostgreSQL uses a message-based protocol for communication between clients and servers. The protocol is supported over TCP/IP and also over Unix-domain sockets. The following table shows how Aurora DSQL supports the [PostgreSQL protocol](https://www.postgresql.org/docs/current/protocol.html). @@ -52,0 +222,8 @@ If you use the AWS CLI in a different environment, make sure that you manually s +PostgreSQL | Aurora DSQL | Notes +---|---|--- +Role (also known as User or Group) | Database Role | Aurora DSQL creates a role for you named `admin`. If you create custom database roles, you must use the admin role to associate them with IAM roles for authenticating when connecting to your cluster. For more information, see [Configure custom database roles](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/using-database-and-iam-roles.html). +Host (also known as hostname or hostspec) | Cluster Endpoint | Aurora DSQL single-Region clusters provide a single managed endpoint and automatically redirect traffic if there is unavailability within the Region. +Port | N/A - use default `5432` | This is the PostgreSQL default. +Database (dbname) | use `postgres` | Aurora DSQL creates this database for you when you create the cluster. +SSL Mode | SSL is always enabled server-side | In Aurora DSQL, Aurora DSQL supports the `require` SSL Mode. Connections without SSL are rejected by Aurora DSQL. +Password | Authentication Token | Aurora DSQL requires temporary authentication tokens instead of long-lived passwords. To learn more, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html).