s3: The ability to specify an IAM role for cross-account interaction

docs/content/s3.md

@@ -745,6 +745,68 @@ If none of these option actually end up providing `rclone` with AWS
 credentials then S3 interaction will be non-authenticated (see the
 [anonymous access](#anonymous-access) section for more info).
 
+#### Assume Role (Cross-Account Access)
+
+If you need to access S3 resources in a different AWS account, you can use IAM role assumption.
+This is useful for cross-account access scenarios where you have credentials in one account
+but need to access resources in another account.
+
+To use assume role, configure the following parameters:
+
+- `role_arn` - The ARN (Amazon Resource Name) of the IAM role to assume in the target account.
+  Format: `arn:aws:iam::ACCOUNT-ID:role/ROLE-NAME`
+- `role_session_name` (optional) - A name for the assumed role session. If not specified,
+  rclone will generate one automatically.
+- `role_session_duration` (optional) - Duration for which the assumed role credentials are valid.
+  If not specified, AWS default duration will be used (typically 1 hour).
+- `role_external_id` (optional) - An external ID required by the role's trust policy for additional security.
+  This is typically used when the role is accessed by a third party.
+
+The assume role feature works with both direct credentials (`env_auth = false`) and environment-based
+authentication (`env_auth = true`). Rclone will first authenticate using the base credentials, then
+use those credentials to assume the specified role.
+
+Example configuration for cross-account access:
+
+```
+[s3-cross-account]
+type = s3
+provider = AWS
+env_auth = true
+region = us-east-1
+role_arn = arn:aws:iam::123456789012:role/CrossAccountS3Role
+role_session_name = rclone-session
+role_external_id = unique-role-external-id-12345
+```
+
+In this example:
+- Base credentials are obtained from the environment (IAM role, credentials file, or environment variables)
+- These credentials are then used to assume the role `CrossAccountS3Role` in account `123456789012`
+- An external ID is provided for additional security as required by the role's trust policy
+
+The target role's trust policy in the destination account must allow the source account or user to assume it.
+Example trust policy:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::SOURCE-ACCOUNT-ID:root"
+      },
+      "Action": "sts:AssumeRole",
+      "Condition": {
+        "StringEquals": {
+          "sts:ExternalID": "unique-role-external-id-12345"
+        }
+      }
+    }
+  ]
+}
+```
+
 ### S3 Permissions
 
 When using the `sync` subcommand of `rclone` the following minimum