Add IAM policy and bucket setup guidance to AWS S3 integration documentation (#38929)

Co-authored-by: Matthew Hallonbacka <79469789+Mallonbacka@users.noreply.github.com>

source/_integrations/aws_s3.markdown

@@ -15,6 +15,75 @@ ha_quality_scale: bronze
 
 The **AWS S3** {% term integrations %} allows you to use [AWS S3](https://aws.amazon.com/s3/) bucket with Home Assistant Backups.
 
+## Prerequisites
+
+This integration requires an existing S3 bucket and an IAM user that has access to that bucket. For security reasons, it is strongly recommended to scope the IAM policy as narrowly as possible to only the required operations and resources.
+
+{% details "Create a new S3 bucket" %}
+
+1. Log in to the [AWS Management Console](https://console.aws.amazon.com/).
+1. Navigate to **S3** from the Services menu.
+1. Click **Create bucket**.
+1. Choose a unique **bucket name** (e.g., `home-assistant-backups-123456`).
+1. Select your preferred AWS **region** (e.g., `eu-central-1`).
+1. Adjust the settings:
+   - ✅ **Block all public access** (enabled by default, recommended)
+   - ⚠️ **Enable Bucket Versioning** (optional). This lets you recover backups after Home Assistant deletes them, but it **can increase storage costs**. Disable this to allow permanent deletion based on retention settings.
+1. Click **Create bucket**.
+
+Make a note of the bucket name — you’ll need it later.
+
+{% enddetails %}
+
+{% details "Create an IAM user" %}
+
+To create a new IAM user that can access the S3 bucket:
+
+1. Go to **IAM > Users** in the AWS Management Console.
+1. Click **Add users**.
+1. Use a name like `home-assistant-backup`.
+1. Check **Access key - Programmatic access** only.
+1. Click **Next: Permissions**.
+
+Now, let's create and attach a custom IAM policy to give the user the necessary permissions to the bucket:
+
+1. Click **Create policy**, go to the **JSON** tab, and paste the following (replace `YOUR_BUCKET_NAME`):
+
+    ```json
+    {
+      "Version": "2012-10-17",
+      "Statement": [
+        {
+          "Sid": "AllowS3BackupOperations",
+          "Effect": "Allow",
+          "Action": [
+            "s3:ListBucket",
+            "s3:GetObject",
+            "s3:PutObject",
+            "s3:DeleteObject",
+            "s3:AbortMultipartUpload"
+          ],
+          "Resource": [
+            "arn:aws:s3:::YOUR_BUCKET_NAME",
+            "arn:aws:s3:::YOUR_BUCKET_NAME/*"
+          ]
+        }
+      ]
+    }
+    ```
+
+1. Name the policy (e.g., `HomeAssistantS3Policy`) and create it.
+1. Return to the user creation wizard and attach the new policy.
+1. Complete the user setup.
+1. Save the **Access Key ID** and **Secret Access Key** — you'll need these when setting up the AWS S3 integration in Home Assistant.
+
+{% enddetails %}
+
+{% note %}
+- Avoid using credentials for your AWS root account or IAM users that have more permissions than is necessary.
+- By limiting credentials to a specific bucket, you reduce risk and help keep your AWS account secure.
+{% endnote %}
+
 {% include integrations/config_flow.md %}
 
 {% configuration_basic %}
@@ -28,6 +97,17 @@ Endpoint URL:
   description: "Endpoint URL provided to [Boto3 Session](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html). Region-specific [AWS S3 endpoints](https://docs.aws.amazon.com/general/latest/gr/s3.html) are available in their documentation. Defaults to `https://s3.eu-central-1.amazonaws.com/`."
 {% endconfiguration_basic %}
 
+## Setting up the AWS S3 integration in Home Assistant
+
+1. In Home Assistant, go to **Settings > Devices & Services**.
+1. Click **Add Integration** and search for **AWS S3**.
+1. Enter the following details:
+   - Access Key ID and Secret Access Key from the IAM user
+   - Your bucket name
+   - The region endpoint (e.g., `https://s3.eu-central-1.amazonaws.com/`)
+
+The integration will test the connection and confirm access to your S3 bucket.
+
 ## Removing the integration
 
 This integration follows standard integration removal. No extra steps are required.