⌘K ctrl+k
Search Shortcut cmd + k | ctrl + k
S3 and AWS Authentication

This page is the entry point for authenticating to S3 and other AWS services from DuckDB. Authentication is configured using secrets, and the detailed reference material lives on the S3 API Support and AWS Extension pages. The sections below explain which method to use and link to the relevant reference.

Choosing an Authentication Method

There are two S3 secret providers. Use the config provider when you have static credentials, and the credential_chain provider when you want DuckDB to fetch credentials automatically through the AWS SDK.

Situation Method Reference
You have a static access key and secret config provider config provider
Credentials come from ~/.aws/credentials or ~/.aws/config profiles credential_chain with a profile Selecting a Profile
You sign in with AWS IAM Identity Center (SSO) credential_chain with the sso chain Single Sign-On (SSO)
You assume an IAM role via STS credential_chain with the sts chain Assuming a Role (STS)
You run on Amazon EKS with IAM Roles for Service Accounts (IRSA) credential_chain with the web_identity chain Web Identity (IRSA)
You run on an EC2 instance and want to use its instance profile credential_chain with the instance chain credential_chain provider
You connect to Amazon RDS or Aurora with IAM authentication rds secret Amazon RDS (IAM Authentication)

The config provider is part of the httpfs extension and works with any S3-compatible storage. The credential_chain provider is AWS-specific and is provided by the aws extension, which is autoloaded on first use.

Static Credentials: the config Provider

Supply the key and secret directly:

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER config,
    KEY_ID 'AKIAIOSFODNN7EXAMPLE',
    SECRET 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    REGION 'us-east-1'
);

See the config provider documentation for the full details, including how to set an explicit ENDPOINT for non-AWS storage.

Automatic Credentials: the credential_chain Provider

The credential_chain provider fetches credentials automatically using the AWS SDK, covering profiles, SSO, assumed roles, web identities (IRSA), and instance metadata. To use the AWS SDK default provider:

CREATE OR REPLACE SECRET secret (
    TYPE s3,
    PROVIDER credential_chain
);

You can select a specific chain with the CHAIN keyword and refine the behavior for each method. The individual mechanisms are documented on the AWS Extension page:

For behavior common to all credential_chain secrets, see Region Resolution, Validation, and Auto-Refresh.

Secret Parameters

The full list of S3 secret parameters that apply to both providers (ENDPOINT, REGION, URL_STYLE, USE_SSL, KMS_KEY_ID, REQUESTER_PAYS, and more) is documented in the Overview of S3 Secret Parameters. Platform-specific secret types for Cloudflare R2 and Google Cloud Storage are also available.

Legacy Authentication

Before DuckDB had a Secrets manager, credentials were loaded through the load_aws_credentials function. This method is deprecated. See the Legacy Authentication Scheme for S3 API page if you are maintaining older setups.

© 2026 DuckDB Foundation, Amsterdam NL
DuckDB Home Code of Conduct Trademark Use Blog