AUTHENTICATE TO AWS WITH SSO

Swamp's AWS integrations — @swamp/s3-datastore, @swamp/aws-sm, and the @swamp/aws/* model family — resolve credentials through the default AWS SDK credential chain. That chain includes SSO profiles, so an IAM Identity Center session works everywhere without extra configuration.

This guide shows you how to sign in and point Swamp at the resulting session.

Sign in and select a profile

An SSO profile lives in ~/.aws/config, not ~/.aws/credentials:

[profile my-sso]
sso_session = my-company
sso_account_id = 123456789012
sso_role_name = PowerUserAccess
region = eu-central-1

[sso-session my-company]
sso_start_url = https://my-company.awsapps.com/start
sso_region = us-east-1

Sign in, then export the profile so Swamp picks it up:

$ aws sso login --profile my-sso
$ export AWS_PROFILE=my-sso

Confirm the session resolves before handing it to Swamp:

$ aws sts get-caller-identity --profile my-sso

Use the profile for an S3 datastore

With AWS_PROFILE exported, set the datastore up as normal — pass no credentials in --config:

$ swamp datastore setup extension @swamp/s3-datastore \
    --config '{"bucket":"my-shared-bucket","prefix":"swamp","region":"eu-central-1"}'

Check that the datastore is reachable under the current session:

$ swamp datastore status

Use the profile for a Secrets Manager vault

The same session backs the vault. region is required in the vault config:

$ swamp vault create @swamp/aws-sm my-aws-sm \
    --config '{"region": "eu-central-1"}' --json
$ swamp vault list-keys my-aws-sm --json

Use a config file at a non-standard path

Set AWS_CONFIG_FILE to the file holding your profiles. The SDK's shared-config loader reads it, so credentials resolve from that path:

$ export AWS_CONFIG_FILE=/etc/swamp/aws-config
$ export AWS_PROFILE=my-sso

Set region explicitly in each profile you use with the @swamp/aws/* model family. Those models read the region from the profile block itself; they do not read it from an [sso-session] block and do not follow source_profile. A profile with no region setting resolves to us-east-1. Setting AWS_REGION or AWS_DEFAULT_REGION also works, and takes priority over the profile.

Refresh an expired session

An SSO session outlives neither the day nor a long-running swamp serve. Each integration reports expiry differently.

The datastore fails within about three seconds and names the profile to re-authenticate:

Datastore session expired: your AWS profile's SSO session is no longer valid. Run 'aws sso login --profile "my-sso"' to refresh, then retry.

The vault reports the same condition in its own vocabulary:

Vault session expired: your AWS profile's SSO session is no longer valid. Run 'aws sso login --profile "my-sso"' to refresh, then retry.

If credentials cannot be resolved at all, the datastore reports the preflight timing out rather than a session expiring:

Credential preflight timed out after 3000ms — verify that AWS credentials are configured (AWS_ACCESS_KEY_ID, AWS_PROFILE, or attached IAM role) and that the credential source is responsive

In every case, run aws sso login --profile <name> and retry the command. The @swamp/aws/* models surface the underlying SDK error instead of these messages; treat a CredentialsProviderError or ExpiredTokenException from a model run the same way.

To keep a short-lived credential fresh inside a vault value rather than in your shell, refer to Auto-Refresh Cloud Credentials.

Give a large first push more time

swamp datastore setup pushes the local .swamp/ directory to the bucket before it reports success, under a 300-second sync timeout. A large first push that overruns it fails and reverts the datastore type. Raise the ceiling with --timeout, in seconds:

$ swamp datastore setup extension @swamp/s3-datastore \
    --timeout 3600 \
    --config '{"bucket":"my-shared-bucket","prefix":"swamp","region":"eu-central-1"}'

--timeout accepts up to 21600 and takes priority over SWAMP_DATASTORE_SYNC_TIMEOUT_MS, which sets the same ceiling in milliseconds for every sync.

A setup that stalls with no output is this timeout, not a credential problem — unresolvable credentials fail within about three seconds with one of the messages above.

Run on EC2 with an instance role

@swamp/s3-datastore disables the SDK's instance metadata lookup unless it detects a container credential source (AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI), or AWS_EC2_METADATA_DISABLED is already set. On a plain EC2 instance whose credentials come from an attached instance profile, set the variable explicitly so the lookup stays enabled:

$ export AWS_EC2_METADATA_DISABLED=false

ECS and EKS tasks need no change — their container credential source is detected and the metadata lookup is left alone.

Reference

Refer to the Datastore configuration reference for the full S3 backend configuration, and to the Vaults reference for vault configuration.