## Object storage for apps

URL: https://docs.atlan.com/apps/packages/references/object-storage-configuration

> Reference guide for configuring cloud object storage connections in Atlan apps

This reference provides complete configuration details for connecting to cloud object storage systems in Atlan apps. Many apps support importing files from cloud object stores, including **Asset Import**, **Relational Assets Builder**, **Lineage Builder**, and **Data Model Ingestion**. This guide covers all common configuration fields and authentication methods across supported providers.

## Prefix (path)

This property specifies the directory or path within your selected cloud object store where the file is located.

- **Optional:** Can be left blank to search from the root of the bucket or container
- **With prefix:** Only files under the specified path are processed
- **Without prefix:** System searches from the root of the storage location
- **Format:** Use forward slashes (`/`) as path separators
- **Trailing slash:** Not required, Atlan appends automatically if missing
- **Path combination:** Prefix + Object key = complete file location (within the bucket or container)

*Example:* If your file is stored in a folder called `imports` inside the `data` directory of your bucket, set the prefix to:

```
data/imports
```

*Example:* For nested paths:

```
production/data-models/2024
```

## Object key (filename)

This property specifies the exact file to import from your chosen cloud object store. The value entered here is combined with the optional **Prefix (path)** to form the complete location of the file.

- **Required:** Must include the file name and extension
- **Single file:** Only one file can be provided per configuration
- **Multiple files:** Requires separate workflow runs for each file, even if they're stored in the same prefix or folder
- **File extension:** Must include the file extension (for example, `.csv`, `.xlsx`, `.json`)
- **Path combination:** Object key + prefix = complete file location (within the bucket or container)

*Example:* If your file is stored under a folder called `data/imports` in your object store, you can configure:

**Prefix:**
```
data/imports
```

**Object key:**
```
customer-data.csv
```

**Complete path:** `{{bucket}}/data/imports/customer-data.csv`

*Example:* For files at the root level:

**Prefix:** (leave blank)

**Object key:**
```
metadata-export.xlsx
```

**Complete path:** `{{bucket}}/metadata-export.xlsx`

## Cloud object store

This property specifies which cloud provider to use for accessing files from object storage. Supported providers are Amazon S3, Google Cloud Storage (GCS), and Azure Data Lake Storage (ADLS). When this option is selected, additional storage-specific properties such as bucket, project ID, or container become available.

### Amazon S3

Amazon S3 enables you to store and retrieve objects at scale. You can use this option when your file is stored in an S3 bucket.

#### AWS access key

The access key for your AWS account. You can find this in the **AWS Management Console > IAM > Users > Security credentials** tab.

- **Required** if you are using access/secret key authentication
- **Keep empty** if you are using tenant-backed, cross-account, or role-based authentication

*Example:*

```
AKIAIOSFODNN7EXAMPLE
```

#### AWS secret key

The secret key that pairs with your access key. This is generated when you create an access key in IAM. You must download it at creation time or rotate and generate a new one if lost. The secret key is only shown once when created, so store it securely. For better security, consider using role-based authentication instead of access keys.

- **Required** if you are using access/secret key authentication
- **Keep empty** if you are using tenant-backed, cross-account, or role-based authentication

*Example:*

```
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
```

#### AWS role ARN

The ARN of the AWS role to use to access S3. You must set this up separately in AWS, and grant permissions for Atlan to assume this role. Role-based authentication is more secure than access keys because it doesn't require storing long-term credentials. The role must have a trust policy that lets Atlan assume it.

- **Required** if you are using role-based authentication method
- **Keep empty** if you are using tenant-backed, cross-account, or access/secret key based authentication

*Example:*

```
arn:aws:iam::123456789012:role/atlan-s3-access-role
```

:::info Role-based authentication
When using role-based authentication, the role must have the necessary S3 permissions (for example, `s3:GetObject` and `s3:ListBucket`) for the bucket and prefix you're accessing.
:::

#### Region

The AWS region in which your bucket is located (for example, `us-east-1`). You can find this in the **S3 service dashboard** when selecting your bucket.

- **Required** if you are using access/secret key authentication
- **Keep empty** in all other scenarios, where the region is inferred from the tenant or role

*Example:*

```
ap-southeast-1
```

*Example:* Common regions:

```
us-east-1
us-west-2
eu-west-1
ap-southeast-1
```

#### Bucket

The name of the S3 bucket that contains your file. The bucket name is listed in the **S3 service dashboard**.

- **Keep empty** to use the tenant-backed object store's bucket (if available)
- **Required** in all other scenarios (cross-account, access/secret keys, and role-based)

*Example:*

```
my-company-data-imports
```

:::info Bucket naming
S3 bucket names must be globally unique and follow AWS naming conventions (lowercase letters, numbers, hyphens, and periods).
:::

### Google Cloud Storage

Google Cloud Storage (GCS) provides durable, secure storage for objects. Use this option if your file is stored in a GCS bucket.

#### Project ID

The ID of your Google Cloud project. You can find this in the **Google Cloud Console > Home Dashboard > Project info** panel.

- **Required** if you are using your own managed GCS bucket
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
my-import-project-123456
```

#### Service account JSON

A JSON key file containing service account credentials with permission to access the bucket. You can create this in the **Google Cloud Console > IAM & Admin > Service accounts**. The service account must have appropriate permissions to read objects from the bucket. Paste the entire JSON content directly into this field.

- **Required** if you are using your own managed GCS bucket
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```json
{
 "type": "service_account",
 "project_id": "my-import-project-123456",
 "private_key_id": "abc123def456...",
 "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----\n",
 "client_email": "atlan-import@my-import-project-123456.iam.gserviceaccount.com",
 "client_id": "123456789012345678901",
 "auth_uri": "https://accounts.google.com/o/oauth2/auth",
 "token_uri": "https://oauth2.googleapis.com/token",
 "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
 "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/atlan-import%40my-import-project-123456.iam.gserviceaccount.com"
}
```

:::info Service account permissions
The service account must have the `Storage Object Viewer` role (or equivalent permissions) for the bucket you're accessing. For write operations, it may need `Storage Object Creator` or `Storage Admin` roles.
:::

#### Bucket

The name of the GCS bucket containing your file. You can find this in the **Cloud Storage > Buckets** page.

- **Required** if you are using your own managed GCS bucket
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
my-company-import-storage
```

### Azure Data Lake Storage

Azure Data Lake Storage (ADLS) provides scalable, secure storage for files and objects. Use this option if your file is stored in an ADLS container.

#### Azure client ID

The application (client) ID for the app registered in Azure AD. You can find this in the **Azure Portal > Azure Active Directory > App registrations**.

- **Required** if you are using your own managed ADLS container
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
12345678-1234-1234-1234-123456789012
```

#### Azure client secret

The client secret value for the registered app. You can generate this in the **Azure Portal > Azure Active Directory > App registrations > Certificates & secrets**. The secret is only shown once when created, so copy it immediately. Store secrets securely and rotate them regularly.

- **Required** if you are using your own managed ADLS container
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
abc123d45pqr678stu901vwx234
```

:::warning Secret expiration
Client secrets have expiration dates. Rotate secrets before they expire, or use certificate-based authentication for long-term access.
:::

#### Azure tenant ID

The tenant ID of your Azure Active Directory instance. This is available in the **Azure Portal > Azure Active Directory > Overview** page.

- **Required** if you are using your own managed ADLS container
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
87654321-4321-4321-4321-210987654321
```

#### Storage account name

The name of your storage account. You can find this in the **Azure Portal > Storage accounts** list.

- **Required** if you are using your own managed ADLS container
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
myimportstorage
```

:::info Storage account naming
Storage account names must be globally unique, between 3-24 characters, and contain only lowercase letters and numbers.
:::

#### Container

The ADLS container that contains your file. The container name is available under **Azure Portal > Storage accounts > Containers**.

- **Required** if you are using your own managed ADLS container
- **Keep empty** if you are using tenant-backed (Atlan-managed) storage

*Example:*

```
data-imports
```

## See also

- [App structure](https://docs.atlan.com/product/capabilities/build-apps/references/app-structure): Learn about standardized folder structure for Atlan applications
- [Widget properties](https://docs.atlan.com/product/capabilities/build-apps/references/widget-properties): Understand UI widget configuration options

---