S3 authentication failures and what each means

Why this matters in production

The four common authentication errors have four unrelated causes, and the one everyone assumes — a wrong secret key — is not the most frequent. The code tells you which investigation to run.

The four errors

SignatureDoesNotMatch is the one that misleads: the secret is often correct and something else about the signed request differs.

Diagnosing SignatureDoesNotMatch

The signature covers the HTTP method, the canonical URI, the query string, selected headers, the payload hash, and a timestamp. Anything that alters one of those between the client and the gateway breaks it.

# 1. clock — check both ends
date -u
ssh rgw-01 date -u
chronyc tracking

# 2. endpoint — the host header is signed
aws --endpoint-url https://rgw.example.com s3 ls        # signed for this host
# a proxy rewriting the Host header breaks the signature

# 3. the credential itself
radosgw-admin user info --uid=analytics | jq '.keys'

# 4. signature version
aws configure set default.s3.signature_version s3v4

The addressing style question

# virtual-hosted: bucket.rgw.example.com — needs wildcard DNS
aws configure set default.s3.addressing_style virtual

# path-style: rgw.example.com/bucket — no DNS requirement
aws configure set default.s3.addressing_style path

RGW supports both, but the host header differs between them and the header is signed. A client using virtual-hosted addressing against a deployment without wildcard DNS fails in a way that presents as a signature error.

ceph config get client.rgw rgw_dns_name

Verifying a credential end to end

export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...
aws --endpoint-url https://rgw.example.com s3 ls
aws --endpoint-url https://rgw.example.com s3 ls s3://known-bucket/

A successful s3 ls proves the credential authenticates. A failure at the second step with success at the first is authorisation, not authentication.

Quiz

Production discipline

Read the specific error code before investigating; the four common S3 auth errors have unrelated causes and the code selects the investigation. Check clocks and test directly against a gateway before concluding a credential is wrong — replacing a correct credential leaves the real cause untouched.

Cross-course references

• Kubernetes: distinguishing authentication from authorisation failures follows the same discipline
• Linux: TLS and Kerberos failures are similarly sensitive to clock skew and hostname mismatches