From 1557d33596127eb6884b7ff83917a057e273da9b Mon Sep 17 00:00:00 2001
From: "STeve (Xin) Huang" <xin.huang@goteleport.com>
Date: Wed, 27 Sep 2023 13:04:08 -0400
Subject: [PATCH] [v14] [docs] DB access troubleshoot sts:AssumeRole not
 authorized (#32661)

* [docs] DB access troubleshot sts:AssumeRole not authorized

* fix spelling

* review comments
---
 .../database-access/aws-troubleshooting.mdx   | 136 ++++++++++++++++++
 1 file changed, 136 insertions(+)

diff --git a/docs/pages/includes/database-access/aws-troubleshooting.mdx b/docs/pages/includes/database-access/aws-troubleshooting.mdx
index 667b52ae96688..81e4f7783d136 100644
--- a/docs/pages/includes/database-access/aws-troubleshooting.mdx
+++ b/docs/pages/includes/database-access/aws-troubleshooting.mdx
@@ -24,3 +24,139 @@ program you can verify connections to databases:
 $ nc -zv postgres-instance-1.sadas.us-east-1.rds.amazonaws.com 5432
 # Connection to postgres-instance-1.sadas.us-east-1.rds.amazonaws.com (172.31.24.172) 5432 port [tcp/postgresql] succeeded!
 ```
+
+### Not authorized to perform `sts:AssumeRole`
+
+The Database Service assumes an IAM role in one of following situations:
+
+- An IAM role is used as `db_user` when accessing AWS services that require IAM
+  roles as database users, such as DynamoDB, Keyspaces, Opensearch, and
+  Redshift Serverless.
+- The `assume_role_arn` field is specified for the database resources or
+  dynamic resource matchers.
+
+<Details title="Role chaining">
+When both of the above conditions are true for a database connection, the
+Database Service performs a role chaining by assuming the IAM role specified
+`assume_role_arn` first then using that IAM role to assume the IAM role for
+`db_user`.
+</Details>
+
+You may encounter the following error if the trust relationship is not
+configured properly between the IAM roles:
+```text
+AccessDenied: User: arn:aws:sts::111111111111:assumed-role/database-service-role/i-* is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::111111111111:role/database-user-role
+```
+
+To allow IAM Role `role1` to assume IAM Role `role2`, the following is
+generally required:
+
+<Details title="1. Configure Trust Relationships on role2">
+`role1` or its AWS account should be set as `Principal` in `role2`'s trust
+policy.
+<Tabs>
+<TabsItem label="Role as principal">
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::111111111111:role/role1"
+      },
+      "Action": "sts:AssumeRole"
+    }
+  ]
+}
+```
+</TabsItem>
+<TabsItem label="Account as principal">
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::111111111111:root"
+      },
+      "Action": "sts:AssumeRole"
+    }
+  ]
+}
+```
+</TabsItem>
+<TabsItem label="Cross-account with external-id">
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::123456789012:role/role1"
+      },
+      "Action": "sts:AssumeRole",
+      "Condition": {
+        "StringEquals": {
+          "sts:ExternalId": "example-external-id"
+        }
+      }
+    }
+  ]
+}
+```
+</TabsItem>
+
+</Tabs>
+</Details>
+
+<Details title="2. Configure Permissions Policies on role1">
+`role1` requires `sts:AssumeRole` permissions, for example:
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": "sts:AssumeRole",
+            "Effect": "Allow",
+            "Resource": "arn:aws:iam::111111111111:role/role2"
+        }
+    ]
+}
+```
+
+Note that this policy can be omitted when `role1` and `role2` are in the same
+AWS account and `role1`'s full ARN is configured as Principal in `role2`'s
+trust policy.
+
+</Details>
+
+<Details title="3. Configure Permissions Boundary on role1">
+`role1` also requires `sts:AssumeRole` permissions in its boundary policy, for
+example:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Action": "sts:AssumeRole",
+            "Effect": "Allow",
+            "Resource": "*"
+        }
+    ]
+}
+```
+
+Note that this is only required when a boundary policy is attached to `role1`.
+</Details>
+
+You can test the trust relationship by running this AWS CLI command as `role1`:
+```code
+aws sts assume-role --role-arn arn:aws:iam::111111111111:role/role2 --role-session-name test-trust-relationship
+```
+
+Learn more on [how to use trust policies with IAM
+roles](https://aws.amazon.com/blogs/security/how-to-use-trust-policies-with-iam-roles/).