AWS aurora-dsql documentation change
Summary
Restructured and expanded documentation on IAM authentication/authorization for cluster management and database connections. Added detailed IAM policy examples, clarified admin vs custom role usage, and revoking authorization procedures.
Security assessment
The changes enhance documentation about IAM policies and role-based access control but do not address a specific disclosed vulnerability. They provide clearer guidance on security best practices like least-privilege permissions (e.g., sample policies with dsql:CreateCluster/dsql:DbConnectAdmin) and revocation procedures, which are security features.
Diff
diff --git a/aurora-dsql/latest/userguide/authentication-authorization.md b/aurora-dsql/latest/userguide/authentication-authorization.md index 52e029131..391f60bbf 100644 --- a//aurora-dsql/latest/userguide/authentication-authorization.md +++ b//aurora-dsql/latest/userguide/authentication-authorization.md @@ -5 +5 @@ -IAM roles to manage clustersIAM roles to connect to clustersPostgreSQL and IAM rolesRevoking authorization using IAM and PostgreSQLUsing IAM policy actions to manage clusters in Aurora DSQLIAM policy to connect to clustersARN format +Managing your clusterConnecting to your clusterPostgreSQL and IAM rolesUsing IAM policy actions with Aurora DSQLRevoking authorization using IAM and PostgreSQL @@ -13 +13 @@ Aurora DSQL uses IAM roles and policies for cluster authorization. You associate -## Manage your clusters using IAM +## Managing your cluster using IAM @@ -15 +15 @@ Aurora DSQL uses IAM roles and policies for cluster authorization. You associate -Cluster management (creating, reading, updating, deleting, tagging) requires you to be authenticated and authorized with IAM to perform those actions. +To manage your cluster, use IAM for authentication and authorization: @@ -17 +17 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you - * Authorization – to manage clusters, you must grant authorization using IAM actions for Aurora DSQL. For example, your IAM identity must have permissions to the IAM action `dsql:CreateCluster` to create a cluster. For more information, see Using IAM policy actions to manage clusters in Aurora DSQL. +**IAM authentication** @@ -19 +18,0 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you - * Authentication – use IAM to manage clusters. You can do so with the [AWS Management Console](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html), [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), or the [AWS SDK](https://docs.aws.amazon.com/sdkref/latest/guide/access.html). @@ -20,0 +20 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you +To authenticate your IAM identity when you manage Aurora DSQL clusters, you must use IAM. You can provide authentication using the [AWS Management Console](https://docs.aws.amazon.com/signin/latest/userguide/how-to-sign-in.html), [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), or the [AWS SDK](https://docs.aws.amazon.com/sdkref/latest/guide/access.html). @@ -21,0 +22 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you +**IAM authorization** @@ -24 +25 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you -## Connect to your cluster using IAM +To manage Aurora DSQL clusters, grant authorization using IAM actions for Aurora DSQL. For example, to create a cluster, make sure that your IAM identity has permissions for the IAM action `dsql:CreateCluster`, as in the following sample policy action. @@ -26 +26,0 @@ Cluster management (creating, reading, updating, deleting, tagging) requires you -To connect to your cluster, you must authenticate with IAM and be authorized to connect to the cluster. When you connect, instead of providing a credential, you use a temporary authentication token. @@ -28 +28,5 @@ To connect to your cluster, you must authenticate with IAM and be authorized to - * Authorization – grant the following IAM policy actions to the IAM identity you’re using to establish the connection to your cluster’s endpoint. + { + "Effect": "Allow", + "Action": "dsql:CreateCluster", + "Resource": "arn:aws:dsql:us-east-1:123456789012:cluster/my-cluster" + } @@ -30 +34 @@ To connect to your cluster, you must authenticate with IAM and be authorized to - * Use `dsql:DbConnectAdmin` if you're using the admin role. Aurora DSQL creates and manages this role for you. +For more information, see Using IAM policy actions to manage clusters. @@ -32 +36 @@ To connect to your cluster, you must authenticate with IAM and be authorized to - * Use `dsql:DbConnect` if you're using a custom database role. You create and manage this role in your database. +## Connecting to your cluster using IAM @@ -34 +38 @@ To connect to your cluster, you must authenticate with IAM and be authorized to - * Authentication – generate an authentication token using an IAM identity with authorization to connect. Provide it as the password when you connect to your database. To learn more, see [Generating an authentication token](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/SECTION_authentication-token.html). +To connect to your cluster, use IAM for authentication and authorization: @@ -36 +40 @@ To connect to your cluster, you must authenticate with IAM and be authorized to - * Authorization expiring – after you establish a connection, the role is authorized until the maximum of one hour for the connection. To learn more, see [ Understanding connections in Aurora DSQL](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/working-with-connections.html). +**IAM authentication** @@ -38,0 +43 @@ To connect to your cluster, you must authenticate with IAM and be authorized to +Generate an authentication token using an IAM identity with authorization to connect. When you connect to your database, provide a temporary authentication token instead of a credential. To learn more, see [Generating an authentication token in Amazon Aurora DSQL](./SECTION_authentication-token.html). @@ -39,0 +45 @@ To connect to your cluster, you must authenticate with IAM and be authorized to +**IAM authorization** @@ -41 +46,0 @@ To connect to your cluster, you must authenticate with IAM and be authorized to -## Interact with your database using PostgreSQL database roles and IAM roles @@ -43 +48 @@ To connect to your cluster, you must authenticate with IAM and be authorized to -To manage database-level authorization, you must use PostgreSQL database roles. Aurora DSQL has two types of roles: an admin role and a custom role. You manage database-level authorization by granting PostgreSQL permissions to your PostgreSQL database roles. +Grant the following IAM policy actions to the IAM identity you’re using to establish the connection to your cluster’s endpoint: @@ -45 +50 @@ To manage database-level authorization, you must use PostgreSQL database roles. -Aurora DSQL creates the admin role for you, and you can't modify it. Connecting as an admin lets you perform actions such as creating new database roles to associate with IAM roles. You must associate your custom database roles with your IAM roles to let the IAM role connect to your database. + * Use `dsql:DbConnectAdmin` if you're using the `admin` role. Aurora DSQL creates and manages this role for you. The following sample IAM policy action permits `admin` to connect to `my-cluster`. @@ -47 +52,5 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting - * Authorization – use the admin role to connect to your cluster. Use PostgreSQL to set up custom database roles and grant permissions. To learn more, see [PostgreSQL database roles](https://www.postgresql.org/docs/current/user-manag.html) and [PostgreSQL privileges](https://www.postgresql.org/docs/current/ddl-priv.html) + { + "Effect": "Allow", + "Action": "dsql:DbConnectAdmin", + "Resource": "arn:aws:dsql:us-east-1:123456789012:cluster/my-cluster" + } @@ -49 +58 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting - * Authentication – use the admin role to connect to your cluster. Use the `AWS IAM GRANT` command to associate the custom database role with the IAM identity with authorization to connect to the cluster. To learn more, see [Authorize database roles to connect to a cluster](./using-database-and-iam-roles.html#using-database-and-iam-roles-custom-database-roles). + * Use `dsql:DbConnect` if you're using a custom database role. You create and manage this role by using SQL commands in your database. The following sample IAM policy action permits a custom database role to connect to `my-cluster`. @@ -50,0 +60,5 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting + { + "Effect": "Allow", + "Action": "dsql:DbConnect", + "Resource": "arn:aws:dsql:us-east-1:123456789012:cluster/my-cluster" + } @@ -54 +67,0 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting -## Revoking authorization using IAM and PostgreSQL @@ -56 +69 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting -**Revoking admin authorization to connect to clusters** +After you establish a connection, your role is authorized up to one hour for the connection. To learn more, see [Understanding connections in Aurora DSQL](./working-with-connections.html). @@ -58 +71 @@ Aurora DSQL creates the admin role for you, and you can't modify it. Connecting -To revoke authorization to connect to your cluster with the admin role, you must revoke the IAM identity's access to `dsql:DbConnectAdmin`. +## Interacting with your database using PostgreSQL database roles and IAM roles @@ -60 +73 @@ To revoke authorization to connect to your cluster with the admin role, you must -After revoking connection authorization from the IAM identity, Aurora DSQL rejects all new connection attempts from that IAM identity. Any active connections using the IAM identity might stay authorized for the connection’s duration. You can find connection duration in [ Quotas and limits](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_quotas.html). To learn more about connections, see [Understanding connections in Aurora DSQL](./working-with-connections.html). +PostgreSQL manages database access permissions using the concept of roles. A role can be thought of as either a database user, or a group of database users, depending on how the role is set up. You create PostgreSQL roles using SQL commands. To manage database-level authorization, grant PostgreSQL permissions to your PostgreSQL database roles. @@ -62 +75 @@ After revoking connection authorization from the IAM identity, Aurora DSQL rejec -**Revoking custom role authorization to connect to clusters** +Aurora DSQL supports two types of database roles: an `admin` role and custom roles. Aurora DSQL automatically creates a predefined `admin` role for you in your Aurora DSQL cluster. You can't modify the `admin` role. When you connect to your database as `admin`, you can issue SQL to create new database-level roles to associate with your IAM roles. To let IAM roles connect to your database, associate your custom database roles with your IAM roles. @@ -64 +77 @@ After revoking connection authorization from the IAM identity, Aurora DSQL rejec -To revoke access to non-admin database roles, you must revoke the IAM identity’s access to `dsql:DbConnect`. +**Authentication** @@ -66 +78,0 @@ To revoke access to non-admin database roles, you must revoke the IAM identity -You can also remove the association between the database role and IAM by using the `AWS IAM REVOKE` operation. To learn more about revoking access from database roles, please see [Revoke database authorization from an IAM role](./using-database-and-iam-roles.html#using-database-and-iam-roles-revoke). @@ -68 +80 @@ You can also remove the association between the database role and IAM by using t -**Revoking database-level privileges** +Use the `admin` role to connect to your cluster. After you connect your database, use the command `AWS IAM GRANT` to associate a custom database role with the IAM identity authorized to connect to the cluster, as in the following example. @@ -70 +81,0 @@ You can also remove the association between the database role and IAM by using t -You can't manage permissions of the admin role. To learn how to manage permissions for custom database roles, see [PostgreSQL privileges](https://www.postgresql.org/docs/current/ddl-priv.html). Modifications to privileges take effect on the next transaction after Aurora DSQL successfully commits the modification transaction. @@ -72 +83 @@ You can't manage permissions of the admin role. To learn how to manage permissio -## Using IAM policy actions to manage clusters in Aurora DSQL + AWS IAM GRANT custom-db-role TO 'arn:aws:iam::account-id:role/iam-role-name'; @@ -74 +85 @@ You can't manage permissions of the admin role. To learn how to manage permissio -The IAM policy action you use depends on the role you use to connect to your cluster and any other IAM actions you need. For example, if your role only needs to be able to get cluster information, then you might limit their permissions to only the `GetCluster` and `ListClusters` permissions. +To learn more, see [Authorizing database roles to connect to your cluster](./using-database-and-iam-roles.html#using-database-and-iam-roles-custom-database-roles). @@ -76 +87,43 @@ The IAM policy action you use depends on the role you use to connect to your clu -The following example policy shows all of the available IAM policy actions for managing clusters. For connecting to clusters, see Using IAM policy actions to connect to clusters. +**Authorization** + + +Use the `admin` role to connect to your cluster. Run SQL commands to set up custom database roles and grant permissions. To learn more, see [PostgreSQL database roles](https://www.postgresql.org/docs/current/user-manag.html) and [PostgreSQL privileges](https://www.postgresql.org/docs/current/ddl-priv.html) in the PostgreSQL documentation. + +## Using IAM policy actions with Aurora DSQL + +The IAM policy action you use depends on the role you use to connect to your cluster: either `admin` or a custom database role. The policy also depends on the IAM actions required for this role. + +### Using IAM policy actions to connect to clusters + +When you connect to your cluster with the default database role of `admin`, use an IAM identity with authorization to perform the following IAM policy action. + + + "dsql:DbConnectAdmin" + +When you connect to your cluster with a custom database role, first associate the IAM role with the database role. The IAM identity you use to connect to your cluster must have authorization to perform the following IAM policy action. + + + "dsql:DbConnect" + +To learn more about custom database roles, see [Using database roles with IAM roles](./using-database-and-iam-roles.html). + +### Using IAM policy actions to manage clusters + +When managing your Aurora DSQL clusters, specify policy actions only for the actions that your role needs to perform. For example, if your role only needs to get cluster information, you might limit role permissions to only the `GetCluster` and `ListClusters` permissions, as in the following sample policy + + + { + "Version" : "2012-10-17", + "Statement" : [ + { + "Effect" : "Allow", + "Action" : [ + "dsql:GetCluster", + "dsql:ListClusters" + ], + "Resource": "arn:aws:dsql:us-east-1:123456789012:cluster/my-cluster" + } + ] + } + +The following example policy shows all available IAM policy actions for managing clusters. @@ -101 +154 @@ The following example policy shows all of the available IAM policy actions for m -## Using IAM policy actions to connect to clusters +## Revoking authorization using IAM and PostgreSQL @@ -103 +156 @@ The following example policy shows all of the available IAM policy actions for m -When connecting to your cluster with the default database role of admin you must use an IAM identity with authorization to perform following IAM policy action. +You can revoke permissions for your IAM roles to access your database-level roles: @@ -104,0 +158 @@ When connecting to your cluster with the default database role of admin you must +**Revoking admin authorization to connect to clusters** @@ -106 +159,0 @@ When connecting to your cluster with the default database role of admin you must - "dsql:DbConnectAdmin" @@ -108 +161 @@ When connecting to your cluster with the default database role of admin you must -When connecting to your cluster with a custom role, you must first associate IAM role with the database role. The IAM identity you use to connect to your cluster must have authorization to perform the following IAM policy action. +To revoke authorization to connect to your cluster with the `admin` role, revoke the IAM identity's access to `dsql:DbConnectAdmin`. Either edit the IAM policy or detach the policy from the identity. @@ -109,0 +163 @@ When connecting to your cluster with a custom role, you must first associate IAM +After revoking connection authorization from the IAM identity, Aurora DSQL rejects all new connection attempts from that IAM identity. Any active connections using the IAM identity might stay authorized for the connection’s duration. You can find connection duration in [ Quotas and limits](https://docs.aws.amazon.com/aurora-dsql/latest/userguide/CHAP_quotas.html). To learn more about connections, see [Understanding connections in Aurora DSQL](./working-with-connections.html). @@ -111 +165 @@ When connecting to your cluster with a custom role, you must first associate IAM - "dsql:DbConnect" +**Revoking custom role authorization to connect to clusters** @@ -113 +166,0 @@ When connecting to your cluster with a custom role, you must first associate IAM -To learn more about custom roles, see [Using database roles with IAM roles](./using-database-and-iam-roles.html). @@ -115 +168 @@ To learn more about custom roles, see [Using database roles with IAM roles](./us -## Amazon Resource Name (ARN) format for Aurora DSQL resources +To revoke access to database roles other than `admin`, revoke the IAM identity’s access to `dsql:DbConnect`. Either edit the IAM policy or detach the policy from the identity. @@ -117 +170 @@ To learn more about custom roles, see [Using database roles with IAM roles](./us -The ARN format for a cluster in Aurora DSQL is `cluster/`<clusterID>``. +You can also remove the association between the database role and IAM by using the command `AWS IAM REVOKE` in your database. To learn more about revoking access from database roles, see [Revoking database authorization from an IAM role](./using-database-and-iam-roles.html#using-database-and-iam-roles-revoke). @@ -119 +172 @@ The ARN format for a cluster in Aurora DSQL is `cluster/`<clusterID>``. -For example, if your cluster ID was `foo0bar1baz2quux3quuux4`, the ARN of the cluster would be `arn:aws:dsql:us-east-1:123456789012:cluster/foo0bar1baz2quux3quux4`. +You can't manage permissions of the predefined `admin` database role. To learn how to manage permissions for custom database roles, see [PostgreSQL privileges](https://www.postgresql.org/docs/current/ddl-priv.html). Modifications to privileges take effect on the next transaction after Aurora DSQL successfully commits the modification transaction.