# Authentication (/connectors/aws/how-to/authentication)



The AWS connector authenticates every request with a **hand-rolled AWS Signature V4 (SigV4)**
verifier (standard-library crypto only — no AWS SDK at runtime). It supports two postures:
**accept-any** (the zero-friction local-dev default) and **configured static credentials** (a
secured connector). Exactly one action — SNS `ConfirmSubscription` — is SigV4-exempt.

## SigV4 verification [#sigv4-verification]

The verifier accepts both signature styles your SDK can produce:

* **header-style** — `Authorization: AWS4-HMAC-SHA256 Credential=…, SignedHeaders=…, Signature=…`;
* **query-style / presigned** — `X-Amz-Algorithm=AWS4-HMAC-SHA256` plus the `X-Amz-*` query params.

The verification rules are the same in both styles:

| Rule                                     | Behavior                                                 |
| ---------------------------------------- | -------------------------------------------------------- |
| Signature compare                        | constant-time (`hmac.Equal`).                            |
| Clock skew                               | ±15 minutes on `X-Amz-Date`.                             |
| Credential scope **service**             | must be `sqs` or `sns`.                                  |
| Credential scope **region**              | **NOT enforced** — any region signs successfully.        |
| `X-Amz-Content-Sha256: UNSIGNED-PAYLOAD` | honored verbatim.                                        |
| `X-Amz-Security-Token`                   | accepted and ignored (no STS / session-token semantics). |

<Callout type="warn">
  **Region is not enforced.** Any `AWS_REGION` your SDK signs with is accepted; the connector's
  default ARN region segment is `kubemq`. The examples use `us-east-1` purely for familiarity. See
  [Migration from AWS](/connectors/aws/reference/migration-from-aws).
</Callout>

## Accept-any mode (the default) [#accept-any-mode-the-default]

When **no credentials are configured**, the credential store is empty: the verifier only parses
the `AccessKeyId` and uses it as the `ClientID`. The middleware logs once on startup —
`aws connector running without credential verification`. This is the default, intended for
zero-friction local development.

<Callout type="warn">
  **Dummy credentials are still required.** Even in accept-any mode the request must carry a
  **syntactically valid** SigV4 signature whose credential-scope service is `sqs` or `sns`. An
  **unsigned** request is rejected with `IncompleteSignature` — the only SigV4-exempt action is SNS
  `ConfirmSubscription`. The signature is not cryptographically checked, but its presence and shape
  are. So your SDK must be given an access key and secret (**any value**) to form the signature.
  Omitting them yields a "missing credentials" SDK error, not a connector error.
</Callout>

```bash
export AWS_ACCESS_KEY_ID="x"       # any value — used as the ClientID in accept-any mode
export AWS_SECRET_ACCESS_KEY="x"   # any value — the SDK needs it to sign
export AWS_REGION="us-east-1"      # not enforced
```

## Configured static credentials [#configured-static-credentials]

When `Credentials` / `CredentialsData` are set, SigV4 is **fully verified**:

* the presented access key must match a configured `AwsCredential.AccessKeyId`;
* the secret must match (a constant-time compare of the signature);
* the authenticated `ClientID` becomes `AwsCredential.ClientID` (defaults to the `AccessKeyId`).

`CredentialsData` is a JSON (optionally base64-encoded) credential array — the env / operator
path. See [Configuration](/connectors/aws/concepts/configuration) for the JSON shape. This is a
getting-started / auth-banner toggle, not a separate example program.

## The ConfirmSubscription exemption [#the-confirmsubscription-exemption]

A request with `Action=ConfirmSubscription`, **no** `Authorization` header, and **no**
`X-Amz-Algorithm` query param bypasses SigV4 entirely (its `ClientID` becomes `sns-confirmation`).
This is the **only** SigV4-exempt action — it exists so the `SubscribeURL` confirmation `GET`
embedded in an SNS `SubscriptionConfirmation` envelope is usable as-is. A **signed**
`ConfirmSubscription` is still verified normally. See
[SNS fan-out](/connectors/aws/how-to/sns-fan-out).

## Casbin authorization [#casbin-authorization]

On top of SigV4, the connector applies per-channel Casbin checks:

* SQS data-plane operations authorize `write` / `read` on `sqs.{queue}`;
* SNS topic management authorizes `write` on the pseudo-resource `sns.{topic}`;
* SNS fan-out applies a per-target `write` check on each `sqs.{queue}` it delivers to.

A denied SQS data-plane operation (for example `SendMessage`) returns `AccessDeniedException`
(403).

## Failure mapping [#failure-mapping]

| Trigger                                                                   | AWS error code          | HTTP |
| ------------------------------------------------------------------------- | ----------------------- | ---- |
| Malformed SigV4 (including an unsigned non-`ConfirmSubscription` request) | `IncompleteSignature`   | 400  |
| Unknown access key (configured-credentials mode)                          | `InvalidClientTokenId`  | 403  |
| Bad signature / clock skew / tampered body                                | `SignatureDoesNotMatch` | 403  |
| Casbin deny on a data-plane operation                                     | `AccessDeniedException` | 403  |

All authentication failures are audited as `aws.auth.failure`. See
[Error codes](/connectors/aws/reference/error-codes).

<Callout type="warn">
  **SigV4 over plain HTTP transmits the request unencrypted.** Accept-any mode is for local
  development only. For production, terminate over the server's HTTPS listener — there is no
  AWS-specific TLS option; TLS comes from the shared server `Security` block. See
  [Connectivity and security](/connectors/aws/how-to/connectivity-and-security).
</Callout>

## Related [#related]

<Cards>
  <Card title="Connectivity and security" href="/connectors/aws/how-to/connectivity-and-security" description="Endpoint override, the opt-in enable, SigV4 over HTTP vs HTTPS, the sticky-LB caveat, and the region/account model." />

  <Card title="Configuration" href="/connectors/aws/concepts/configuration" description="Accept-any vs static credentials, the CredentialsData JSON shape, and the connector enable variable." />

  <Card title="Auth & security" href="/connectors/reference/auth-and-security" description="The shared TLS/mTLS and security model across KubeMQ connectors." />
</Cards>