# Connect your Hygraph project to AWS S3

Learn how to connect your Hygraph project to AWS S3

**AWS S3** is a service that provides object storage through a web service interface.

## What you can do with the Hygraph-AWS S3 integration

With this app you can access assets stored in your AWS S3 bucket directly from the Hygraph UI and then use them in your Hygraph project.

## Prerequisites to use this integration

- You must have a **Hygraph** account. If you don't have one, you can create one [here](https://app.hygraph.com/signup).
- You must have a [Hygraph project](https://hygraph.com/docs/getting-started/fundamentals/quickstart#create-a-project) with at least one [model](https://hygraph.com/docs/getting-started/fundamentals/quickstart#create-a-model).
- You must have an **AWS** account. If you don't have one yet, you can create one [here](https://portal.aws.amazon.com/billing/signup#/start/email).
- You must have your `Access key` and `Secret access key` ready. [Here](https://hygraph.com/docs/integrations/connect-aws-s3#user-setup) you can see how to get them.
- You must have access to AWS bucket. We explain how to do this [here](https://hygraph.com/docs/integrations/connect-aws-s3#access-to-aws-bucket).

**Warning:**

**Apps are environment specific**. This means their configuration is applied per environment. Take this into consideration if you're working with a project using more than one environment.

## Install the AWS S3 app

Click [here](https://app.hygraph.com/apps/aws_s3/new) to install the AWS S3 App on **Hygraph**, then follow these steps:

[Video](https://www.youtube.com/watch?v=GeIx4r0XxGU)

1. Use the dropdowns to select which project and environment you want to install the app in, then click `Install app`.
2. The permissions pop-up will display. Clicking `Authorize app` finishes the installation and takes you to the app configuration screen.
3. Next, you need to configure the app. To do that, you first need to fill in your credentials. We explained how to get this information [in the prerequisites section](https://hygraph.com/docs/integrations/connect-aws-s3#prerequisites-to-use-this-integration).
4. Click `Save config settings` to finish the configuration process. A pop-up notification in the bottom right corner of the screen will indicate that the changes have been saved.

## Add the AWS S3 field to a model

[Video](https://www.youtube.com/watch?v=y3mABvNQJKE)

1. Navigate to the **Schema** builder.
2. Select the model that you want to add the **S3** field to.
3. Select the **S3** field from the **Add fields** right sidebar.
4. Complete the `Display name` field, and the `API ID` will be auto-filled by the system. Optionally, you can also add a `Description`.
5. This screen also allows you to control different properties of your Akeneo field: you can allow multiple values, or you can localize the field, by selecting the checkboxes in the `Field options` section.
6. Click `Add`.

## Use AWS S3 in the Content editor

[Video](https://www.youtube.com/watch?v=jUFZw2ubxdk)

1. Navigate to the **Content** editor.
2. Select the view that you configured the **S3** field for.
3. Click `+ Add entry` to create a new entry or, alternatively, edit an existing entry by clicking on the pencil icon.
4. Locate the **S3** section of the screen and click on `Add S3 asset`. This opens a new screen where you can select and export assets into your Hygraph content entry. This screen shows the root folder selection as default view.

  **Pro Tip:**
  - The selected root is the top level allowed, you cannot go back from that.
  - The overall root of the bucket is identified with a `/` alone. You can navigate the folders from the root on.

5. Select the asset(s) you want, and then click `Export`. If you configured your S3 field to allow multiple assets, you will be able to use the checkboxes to select several assets here.
6. After selecting the asset(s) you want and returning to the content entry, your selection will display on the list. You can optionally use the six dots icon to drag and drop the assets on the list to organize them in the order you want.
7. Finally, click `Save` or `Save & Publish`, as needed.

## Access to AWS bucket

### User setup

[Video: AWS Bucket - User setup](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9gshu5h07vx8mg5snv4)

1. Go to **Amazon IAM > Users** and click `Create user` to create a new one.
2. Attach a policy clicking `Add permissions` in your user details view. You can either add the user to a group or attach policies directly.

    **Minimal list of permissions needed::**

    - `GetObject`
    - `ListBuckets`
    - `ListObjectsV2`
    - `PutObject`

3. Go to **Security credentials** and click `Create access key` to create a new access key. You can only have two at a time, so if you have two already the button will be grayed out.
4. Under **Access key best practices & alternatives**, select `Third-party service`.
5. Copy your `Access key` and `Secret access key` and store them somewhere safe.

### Bucket setup

[Video: AWS Bucket - Bucket setup](https://eu-central-1-shared-euc1-02.graphassets.com/AvHQ3RDvFSousA8iwElOKz/cmnn9x9eehu5907vxa57fn2gk)

1. Go to **Amazon S3 > Buckets** and click `Create bucket` to create a new one.
2. In your bucket's detail view, go to **Permissions** and disable `Block all public access`.
3. Add a bucket policy.

**Parts of the policy:**

```json
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::aorltestbucket/*"
}
```

Public read access allows using assets that you store in this bucket on your public website after being selected in Hygraph:

```json
{
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::688394999555:user/ao-test-user"
            },
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::aorltestbucket/*"
        }
```

In the example above, `Principal` is the user you have created earlier, and `Resource` is the name of your bucket.

This policy allows the user that we'll be using to connect the Hygraph app to manage assets.

## Resources

- [AWS S3 documentation](https://docs.aws.amazon.com/s3/)