AWS Common (Shared AWS Authentication)

aws_common is a shared authentication component used by connectors that talk to AWS services (for example, S3 or STS). It defines how the connector authenticates to AWS and how it builds the AWS SDK configuration used for API calls.

This page documents the authentication methods and configuration fields exposed by AWS-based connectors that rely on aws_common.

Source Setup Guide

To set up AWS Common authentication, choose one of the supported authentication methods and provide the required AWS credentials/role details for the AWS services used by the source connector.

Supported methods:

• Environment credentials (Env): Uses the standard AWS credential resolution chain (for example, environment variables, shared credentials/config files, or instance/task roles).
• Assume role (Role): Assumes an IAM role via AWS STS using environment credentials as the base credentials. Optionally supports an external ID.
• Static credentials (AccessKey): Uses an AWS access key ID and secret access key (optionally with a session token).

Notes:

• When using Assume role, the connector uses AWS STS and will automatically retry transient failures while assuming the role. STS calls also use conservative connect and operation timeouts to avoid hanging during authentication.

Setup

Before configuring an AWS-based connector, decide which authentication method you will use:

• Environment credentials (recommended when running in AWS): Use the default AWS credential provider chain (IAM role for service account, instance profile, ECS task role, etc.).
• Assume role: Use environment credentials as a base identity, then assume a target IAM role via AWS STS.
• Static access keys: Provide an access key ID and secret access key (optionally a session token).

You will also need to know the AWS region for the service you are connecting to.

Authentication

Uses the AWS SDK default credential provider chain. This typically includes (in order) environment variables, shared config/credentials files, and AWS workload/instance/task roles depending on where the connector runs.

Common environment variables:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN (optional, for temporary credentials)
• AWS_REGION / AWS_DEFAULT_REGION (some connectors may still require an explicit region field)

Option 2: Assume role (Role)

Assumes an IAM role using AWS STS AssumeRole.

Required:

• role_arn

Optional:

• external_id (recommended when assuming roles across accounts)

Notes:

• The connector first loads credentials from the environment provider chain, then calls STS to assume the specified role.
• The assumed role session name is generated automatically.
• STS assume-role requests use timeouts (10s connect timeout, 30s operation timeout) and are retried up to 4 attempts if they fail.

Option 3: Static access keys (AccessKey)

Provide AWS credentials directly.

Required:

• access_key_id
• secret_access_key

Optional:

• session_token (required if you are using temporary credentials)

Configuration fields

The exact configuration surface depends on the specific AWS connector, but AWS-based connectors using aws_common typically expose the following fields.

Field	Type	Required	Description
region	string	Yes	AWS region to use (for example, us-east-1).
auth.type	string	Yes	Authentication mode. One of: env, role, access_key.
auth.role_arn	string	If auth.type=role	ARN of the IAM role to assume.
auth.external_id	string	No	External ID to use when assuming a role.
auth.access_key_id	string	If auth.type=access_key	AWS access key ID.
auth.secret_access_key	string	If auth.type=access_key	AWS secret access key.
auth.session_token	string	No	AWS session token for temporary credentials.

Retries and resiliency

AWS SDK requests made through aws_common use the AWS SDK standard retry strategy with a maximum of 10 attempts per request.

Streams

aws_common is a shared authentication module and does not define streams by itself. Streams are defined by the specific AWS source connector that uses this authentication.