> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3 Connection

> Connect so that large files can be read directly from S3

## What is an S3 Connection?

When you place large files that are hard to upload through the browser in an Amazon S3 bucket, OneSight reads them directly at query time. Files are not copied or stored, so replacing the original takes effect starting with the next query.

<Note>
  Only users with **Admin** privileges can register a data source. The AWS-side setup (Step 1) must be handled by the person who manages that bucket.
</Note>

## What You'll Need

* The **bucket name** and **region** to connect (e.g., `ap-northeast-2`)
* AWS permissions to set up one of the two authentication methods below

## Two Authentication Methods

| Method                            | Description                                                                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Role Delegation** (Recommended) | Create a read-only role in your AWS account and delegate its use to OneSight. **No long-lived access keys are shared.** |
| **Access Key**                    | Issue a read-only access key and secret key and enter them. Simpler to set up.                                          |

<Note>
  S3-compatible storage (MinIO, Cloudflare R2, etc.) does not support role delegation. In that case, use the **Access Key** method.
</Note>

## Step 1: Prepare Read-Only Permissions (AWS)

OneSight only needs the two permissions below. Do not grant permissions to upload or delete files, since they are not used.

| Permission      | Purpose                                 |
| --------------- | --------------------------------------- |
| `s3:ListBucket` | Shows the list of folders and files     |
| `s3:GetObject`  | Reads the contents of the selected file |

<Steps>
  <Step title="Create a Policy">
    In the AWS Console, go to **IAM → Policies → Create policy**, select the **JSON** tab, and paste the content below.
    Replace both instances of `my-bucket` with your actual bucket name.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "OneSightListBucket",
          "Effect": "Allow",
          "Action": ["s3:ListBucket"],
          "Resource": "arn:aws:s3:::my-bucket"
        },
        {
          "Sid": "OneSightReadObjects",
          "Effect": "Allow",
          "Action": ["s3:GetObject"],
          "Resource": "arn:aws:s3:::my-bucket/*"
        }
      ]
    }
    ```

    The two statements are shaped differently on purpose. Listing applies to the **bucket itself**, while reading files applies to the **objects inside the bucket** (`/*`).

    Give the policy a clear name, such as `onesight-readonly`.
  </Step>
</Steps>

Which entity this policy is attached to differs depending on the authentication method. Only proceed with the method you chose below.

### Role Delegation (Recommended)

<Steps>
  <Step title="Check Two Values in the OneSight Console">
    In the console, open **Data Sources → Add → Storage → Amazon S3** and switch the authentication method to **Role Delegation**. The **Principal ARN** and **External ID** will be displayed. Copy both values.

    <Warning>
      Always use the **value shown in the console** for the Principal ARN. It differs by environment, so copying the example from this document would cause you to trust the wrong principal.
    </Warning>
  </Step>

  <Step title="Create a Role and Specify the Trust Policy">
    In **IAM → Roles → Create role**, select **Custom trust policy** and paste the content below. Replace both angle-bracket placeholders with the values you copied in the previous step.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": { "AWS": "<Principal ARN shown in the console>" },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": { "sts:ExternalId": "<External ID shown in the console>" }
          }
        }
      ]
    }
    ```

    You **must** include the `sts:ExternalId` condition. Without it, a third party who discovers the role ARN could use that role through OneSight.
  </Step>

  <Step title="Attach Permissions and Copy the Role ARN">
    In the permissions step, attach the `onesight-readonly` policy you created earlier, then create the role. Copy the **ARN** of the created role.
  </Step>
</Steps>

<Note>
  The External ID is **fixed per organization**. It doesn't change even if you register multiple data sources or re-register one, so once you set up the trust policy, it remains valid.
</Note>

### Access Key Method

<Steps>
  <Step title="Create a User and Attach the Policy">
    Create a user dedicated to OneSight under **IAM → Users → Create user**, and during the permissions step, choose **Attach policies directly** to attach the policy you created earlier.

    Since this isn't an account a person will log in with, you don't need to grant console login access.
  </Step>

  <Step title="Issue an Access Key">
    In the created user's **Security credentials** tab, select **Create access key**, and choose **Application running outside AWS** (third-party service) as the use case.

    Copy the issued **access key** and **secret key** and store them somewhere safe.
  </Step>
</Steps>

<Warning>
  The secret key is shown **only once** when it's issued. You cannot view it again afterward, so be sure to store it somewhere safe. If you lose it, you'll need to issue a new key.
</Warning>

## Step 2: Connect to OneSight

<Steps>
  <Step title="Select Storage">
    Choose **Data Sources → Add → Storage → Amazon S3**.
  </Step>

  <Step title="Enter Connection Details and Connect">
    Choose the **authentication method** you selected in Step 1, enter the items below, and verify the connection.

    | Field                   | Description                                                      |
    | ----------------------- | ---------------------------------------------------------------- |
    | Role ARN                | *Role Delegation method* — the ARN of the role created in Step 1 |
    | Access key / Secret key | *Access Key method* — the keys issued in Step 1                  |
    | Region                  | The region where the bucket is located (e.g., `ap-northeast-2`)  |
    | Bucket                  | The name of the bucket to connect                                |
    | Endpoint                | Enter only when using S3-compatible storage (see below)          |
    | Path                    | Enter to browse only a specific folder (optional)                |

    The secret key entered with the Access Key method is **encrypted with AES-256-GCM before being stored** at registration, and is never shown on screen again. The Role Delegation method has no long-lived secret to store.
  </Step>

  <Step title="Select a File">
    Click a folder to navigate, then select the file to use. For SQLite (`.db`) files, next choose the **table** to query.
  </Step>

  <Step title="Review and Register">
    Check the data in the preview, review the automatically suggested mapping, then give it a name and register it.
  </Step>
</Steps>

## S3-Compatible Storage

S3-compatible storage such as MinIO, Cloudflare R2, Wasabi, and NAVER/NHN/KT Cloud connects the same way. Enter that storage's address as the **Endpoint**, and enable the **path-style** option if needed. This also applies if you're running MinIO on a NAS.

Role delegation is an AWS-specific feature, so it isn't available on S3-compatible storage. Connect using the **Access Key** method instead.

<Warning>
  The endpoint must be an **address reachable from outside**. Addresses that are only reachable within an internal network or VPN are blocked by security policy.
</Warning>

## Supported File Types and Size Limits

| Type                    | Size Limit                                       |
| ----------------------- | ------------------------------------------------ |
| CSV                     | No limit — reads up to the first 4MB of the file |
| Excel (`.xlsx`, `.xls`) | 32MB                                             |
| JSON                    | 32MB                                             |
| SQLite (`.db`)          | 256MB                                            |

Excel, JSON, and SQLite have size limits because their formats require the entire file to be downloaded before it can be opened. A notice is shown at the registration step if the limit is exceeded.

## Next Steps

<CardGroup cols={2}>
  <Card title="SFTP Connection" icon="terminal" href="/en/data-sources/sftp">
    Connect files on an SFTP server
  </Card>

  <Card title="Contact Us" icon="message" href="/en/support/tickets">
    Contact us if you can't get connected
  </Card>
</CardGroup>