# Share a bucket with another organization

Let another organization, or one IAM user of any organization, read or write objects in your bucket by naming them in the bucket policy.

Name them in the bucket policy's `Principal`, under the key `EWS` (or `AWS`). This is not public, so it works with Block public
access on. Replace _example-exchange_ with your bucket's name and
_6a1f0c2e-8b3d-4e5f-9a7b-1c2d3e4f5a6b_ with the partner organization's id.

## Prerequisites

- Permission for `s3:PutBucketPolicy` on the bucket.
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- The id of the other organization (each organization sees its own as **Organization ID** under
  **Settings**), or the id of the IAM user and of their organization.

## Write the policy

| Principal entry                       | Covers                                                                |
| ------------------------------------- | --------------------------------------------------------------------- |
| `<organization id>`                   | every user and key of that organization, as far as its own IAM allows |
| `arn:aws:iam::<organization id>:root` | the same, in AWS's spelling                                           |
| `rn:ews::<org>:iam:user/<id>`         | one IAM user of any organization, and the keys that act as them       |

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "EWS": ["6a1f0c2e-8b3d-4e5f-9a7b-1c2d3e4f5a6b"] },
      "Action": ["s3:GetObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::example-exchange/partner/*"
    }
  ]
}
```

## Save it

**Console**
1. Open the bucket, then choose **Public access**.
2. Under **Bucket policy**, for **Policy document (JSON)**, paste the policy.
3. Choose **Save policy**.

The console says "Policy saved."

**CLI**
```sh
dcloud s3 bucket-access set-policy example-exchange --policy "$(cat policy.json)"
```

**API**
```http
PUT /s3/api/buckets/example-exchange/policy
{ "policy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"EWS\":[\"6a1f0c2e-8b3d-4e5f-9a7b-1c2d3e4f5a6b\"]},\"Action\":[\"s3:GetObject\",\"s3:PutObject\"],\"Resource\":\"arn:aws:s3:::example-exchange/partner/*\"}]}" }
```

**Terraform**
```hcl
resource "dcloud_bucket_policy" "exchange" {
  bucket = dcloud_bucket.exchange.id
  policy = file("policy.json")
}
```

## Result

- A request from the other organization is allowed only when both your bucket policy and the
  caller's own IAM policies allow it, as across AWS accounts. Their administrators decide which of
  their users may use what you shared.
- The other organization reads and writes the objects you shared with their own keys, at the same
  endpoint. It can never change the bucket's policy, Block public access, website or any other
  setting.
- Users of your own organization are allowed when either their IAM policies or the bucket policy
  allows it. A `Deny` in either always wins.

## If it is refused

- 400 `Invalid principal in policy: …`: every named organization and user must exist.
- 400 `… "*" cannot be mixed with named principals`: `*` and names in one `Principal`.
- 400 `… unknown principal "…"`: an entry that is none of the three forms above.
- 400 `A bucket policy may be at most 20 KB`.
- 403 `This bucket is managed by the platform; its access cannot be changed`.

## Related

- [Access control](access-control.md)
- `s3.bucket-access.set-policy` · `dcloud s3 bucket-access set-policy` · `dcloud_bucket_policy`
