Calling AWS APIs from C#: the SDK and a hand-written SigV4 signer
Configure AWS SDK for .NET v4 clients properly (credentials, Region, retries, timeouts, paginators, DI), then sign an AWS request by hand with Signature Version 4 so you understand exactly what the SDK does and can debug SignatureDoesNotMatch errors.
Assumes: .NET 10 LTS · AWS SDK for .NET v4 (AWSSDK.Core 4.1.x, AWSSDK.SecurityToken 4.1.x, AWSSDK.Extensions.NETCore.Setup 4.1.x) · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-17.
Learning objectives
By the end of this lesson you can:
- Register AWS SDK for .NET v4 clients with dependency injection (
AddDefaultAWSOptions,AddAWSService<T>()) and explain how credentials and Region are resolved. - Use SSO profiles locally and IAM roles in AWS, and configure retries, timeouts and paginators correctly.
- Handle v4's breaking changes: null collections and nullable value types.
- Walk through Signature Version 4: canonical request, string to sign, signing-key derivation, signature,
Authorization,X-Amz-DateandX-Amz-Security-Token— and say what presigned URLs and SigV4a change. - Hand-sign an STS
GetCallerIdentityrequest in C# (Lab 4.5) and compare it with the SDK. - Diagnose
SignatureDoesNotMatch, clock-skew and encoding errors.
Prerequisites
- Service-to-service communication is the next lesson and builds on this one
- Module 3: .NET on AWS — SDK basics and configuration
- Module 5: Security — IAM roles and policies (recommended)
- Tools: .NET 10 SDK, AWS CLI v2, and
aws sso login --profile learn-sandboxworking - Lab: SigV4 signer walkthrough, code in
labs/m04-sigv4-signer/
Why this matters in banking
Harbourline's outbound proxy team "harmlessly" started normalising header whitespace. Overnight, every batch job that called an IAM-authorised private API through the proxy failed with 403 SignatureDoesNotMatch. Nobody on the payments team knew what was signed, so it took two days to find. Another team hard-coded a long-lived access key into a reconciliation tool because "the SDK didn't find credentials" — the real cause was a missing AWSSDK.SSO package.
Knowing how the SDK finds credentials, and what exactly SigV4 signs, turns both incidents into ten-minute fixes — and SigV4 is how you will sign service-to-service calls to IAM-protected APIs.
The idea in plain language
Every AWS API call is an HTTPS request with a signature. The SDK builds a summary of the request (method, path, query, selected headers, a hash of the body), signs it with a key derived from your secret access key, and attaches the signature. AWS repeats the calculation with its copy of your key; if the results match and IAM allows the action, the call proceeds. The secret itself never travels.
The signing key is scoped: derived for one date, one Region and one service. A leaked signature is useless for other services or Regions, and the timestamp limits replay: in most cases a request must reach AWS within five minutes of its timestamp.
Analogy: A bank teller verifies a cheque by checking the signature against the card on file — the account holder never hands over their pen. SigV4 goes further: each cheque is signed with a pen issued for that day, that branch and that type of transaction, and it is void if presented more than five minutes after it was written.
What problem the AWS SDK solves
| Concern | What the SDK v4 does | What you still own |
|---|---|---|
| Credentials | Resolves a chain: explicit → env vars → web identity → profile (AWS_PROFILE / [default]) → container credentials → EC2 instance metadata | Never ship access keys; use roles in AWS and SSO locally |
| Region | From client config, AWS_REGION, or profile | Set it explicitly in config to avoid surprises |
| Signing | SigV4 (SigV4a automatically for multi-Region features such as S3 Multi-Region Access Points) | Keep the clock in sync |
| Retries | RetryMode defaults to Standard in v4; MaxErrorRetry 2 for most services | Choose Adaptive for heavy throttling; never stack Polly retries on top |
| Timeouts | Async calls honour your CancellationToken | Pass a token with a deadline |
| Pagination | client.Paginators.X(...) returns IAsyncEnumerable results | Create a new paginator per enumeration |
v4 changes that bite .NET developers: response and request collections now default to null (restore v3 behaviour with AWSConfigs.InitializeCollections = true); value-type properties became nullable (int?, bool?, DateTime?); credential providers that rely on STS use the regional STS endpoint; and the SDK always uses SigV4. SSO profiles need the AWSSDK.SSO and AWSSDK.SSOOIDC packages referenced, or credential resolution fails at runtime.
Microsoft / Azure comparison
| You know (Microsoft/Azure) | AWS equivalent | What's different |
|---|---|---|
DefaultAzureCredential | SDK default credential chain (DefaultAWSCredentialsIdentityResolver) | Similar idea; the AWS chain is ordered differently and uses profiles |
az login + developer credential | aws sso login --profile learn-sandbox + SSO profile | SDK needs AWSSDK.SSO and AWSSDK.SSOOIDC |
| Managed identity on App Service / Functions | IAM role for Lambda (execution role) / ECS task role | Credentials delivered by the platform, rotated automatically |
services.AddAzureClients(...) | AddDefaultAWSOptions + AddAWSService<T>() | Clients registered as singletons by default |
| Bearer tokens from Entra ID on every call | SigV4 signature on every call | No token endpoint; the request itself is signed |
| SAS URL for Blob Storage | S3 presigned URL (SigV4 in the query string) | Up to 7 days with long-term keys; shorter with role credentials |
AsPages() on AsyncPageable<T> | client.Paginators.X(...).Responses / key results | Paginators are single-use |
Architecture
Security-boundary view: the long-term secret stays with IAM Identity Center or the platform; your process holds short-lived keys; only the derived signature crosses the network; and IAM authorises the action after the signature is verified.
Step-by-step implementation
Configure the SDK the .NET way
Add AWSSDK.Extensions.NETCore.Setup, the service packages you use, and — for local SSO — AWSSDK.SSO and AWSSDK.SSOOIDC. Put "AWS": { "Profile": "learn-sandbox", "Region": "us-east-1" } in appsettings.Development.json only; in AWS no profile is set, so the chain finds the role credentials.
Register clients once
services.AddDefaultAWSOptions(configuration.GetAWSOptions()) then services.AddAWSService<IAmazonSecurityTokenService>(). Clients are thread-safe singletons; do not create one per request.
Respect v4's null collections and use paginators
Check collections for null before enumerating. For list APIs, prefer paginators over hand-written NextToken loops.
Sign one request by hand
Build the canonical request, hash it, build the string to sign, derive the signing key, compute the signature and add the headers. Compare your intermediate strings with the test vectors and with what AWS echoes in error messages.
Compare with the SDK
Call the same API through AmazonSecurityTokenServiceClient. Both should return the same ARN — proof that you reproduced the SDK's signing.
Signature Version 4, step by step
The worked example signs STS GetCallerIdentity at 2026-11-17T09:30:00Z with AWS's documented example key (AKIAIOSFODNN7EXAMPLE / wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY). The hashes below were computed for this exact input, so you can check your implementation against them.
1. Canonical request — six parts joined by newlines: method, canonical URI, canonical query string, canonical headers (each name:value line ends with a newline, which is why a blank line follows), signed headers, and the hex SHA-256 of the body.
POST
/
content-type:application/x-www-form-urlencoded; charset=utf-8
host:sts.us-east-1.amazonaws.com
x-amz-date:20261117T093000Z
content-type;host;x-amz-date
ab821ae955788b0e33ebd34c208442ccfc2d406e2edc5e7a39bd6458fbb4f843Rules that matter:
- Header names lowercase, sorted; values trimmed with internal runs of spaces collapsed to one.
hostand everyx-amz-*header you send must be signed; signingcontent-typetoo is good practice. Do not sign hop-by-hop headers such asconnectionoruser-agent, which proxies change. - Query string: URI-encode each name and value separately (
%20for space, never+; uppercase hex; onlyA–Z a–z 0–9 - . _ ~unencoded), then sort by name. A parameter with no value isname=. - Path: for most services each path segment is URI-encoded again on top of the encoding it already has in the URL ("double encoding"); Amazon S3 is the exception and uses the path encoded once, without normalisation. (The current IAM guide documents the S3 no-normalisation rule; the double-encoding rule comes from the earlier SigV4 documentation and the SDK signers ⚠ VERIFY wording against the current guide.)
- Payload hash: SHA-256 of the body; for an empty body
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. S3 can use the literalUNSIGNED-PAYLOAD(sent inx-amz-content-sha256), and VPC Lattice requires it.
2. String to sign — algorithm, timestamp, credential scope, and the hex SHA-256 of the canonical request:
AWS4-HMAC-SHA256
20261117T093000Z
20261117/us-east-1/sts/aws4_request
8fea968c4fc0abd86c9f9a8441a330ac1331418a833e92021ca5cb16c7ed425e3. Signing key — a chain of HMAC-SHA256 operations:
kDate = HMAC("AWS4" + secretKey, "20261117")
kRegion = HMAC(kDate, "us-east-1")
kService = HMAC(kRegion, "sts")
kSigning = HMAC(kService, "aws4_request")
= 7164e55f62337519e36d022df8bfbcb657bc808e0582cc74873f4df51d9b11cc4. Signature — hex(HMAC(kSigning, stringToSign)) = 6be3b8d0c0c50bd9420c9fdc718412530ffb4ed194f23b81eefab27b30c87804.
5. Headers — the Authorization value is one line (no comma between the algorithm and Credential):
X-Amz-Date: 20261117T093000Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20261117/us-east-1/sts/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=6be3b8d0c0c50bd9420c9fdc718412530ffb4ed194f23b81eefab27b30c87804With temporary credentials (SSO, roles), also send X-Amz-Security-Token. Most services accept it signed (add it to the canonical headers); a few want it added after signing — check the service's documentation.
Presigned URLs put the same information in the query string (X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, X-Amz-Signature, optionally X-Amz-Security-Token). X-Amz-Expires ranges from 1 to 604,800 seconds (seven days), because the signing key is valid for at most seven days; with role credentials the URL also dies when the session ends.
SigV4a (AWS4-ECDSA-P256-SHA256) uses an ECDSA key pair derived from your secret, drops the Region from the credential scope and adds an X-Amz-Region-Set header, so one signature is valid in several Regions. The SDK switches to it automatically for features such as S3 Multi-Region Access Points.
AWS Console instructions
There is nothing to create. To see signing in practice: IAM Identity Center access portal → your account → Access keys shows the temporary key, secret and session token that a profile resolves to (never paste these into code). CloudTrail → Event history, filter Event name = GetCallerIdentity, shows your hand-signed call with the role session name, proving AWS accepted it.
AWS CLI
# Sign in and confirm who you are (STS GetCallerIdentity needs no IAM permission)
aws sso login --profile learn-sandbox
aws sts get-caller-identity --profile learn-sandbox
# Watch the CLI build its canonical request and string to sign (debug output is verbose)
aws sts get-caller-identity --profile learn-sandbox --debug 2>&1 | grep -A 12 "CanonicalRequest"
# Generate an S3 presigned URL valid for 5 minutes (only if you have a test bucket)
aws s3 presign s3://hl-m04-sigv4-demo-REPLACE/statement.pdf --expires-in 300 --profile learn-sandboxInfrastructure as Code
Not applicable: this lesson creates no AWS resources. The lab only calls STS, which has no infrastructure. The IAM roles that provide credentials in AWS are covered in Service-to-service communication.
Complete code
The full lab is in labs/m04-sigv4-signer/ (SigV4Signer, CanonicalRequest, SigningKey, AwsCredentials, the demo console app and tests against AWS's published test vectors). The excerpts below compile together.
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
namespace Harbourline.SigV4;
public sealed record AwsCredentials(string AccessKeyId, string SecretAccessKey, string? SessionToken);
public sealed record SigningResult(string CanonicalRequest, string StringToSign, string Signature);
public static class SigningKey
{
public static byte[] Derive(string secretAccessKey, string dateStamp, string region, string service)
{
var kDate = HMACSHA256.HashData(Encoding.UTF8.GetBytes("AWS4" + secretAccessKey), Encoding.UTF8.GetBytes(dateStamp));
var kRegion = HMACSHA256.HashData(kDate, Encoding.UTF8.GetBytes(region));
var kService = HMACSHA256.HashData(kRegion, Encoding.UTF8.GetBytes(service));
return HMACSHA256.HashData(kService, Encoding.UTF8.GetBytes("aws4_request"));
}
}
public static class CanonicalRequest
{
public static string UriEncode(string value, bool encodeSlash = true)
{
var sb = new StringBuilder();
foreach (var b in Encoding.UTF8.GetBytes(value))
{
var c = (char)b;
if (char.IsAsciiLetterOrDigit(c) || c is '-' or '.' or '_' or '~' || (c == '/' && !encodeSlash))
sb.Append(c);
else
sb.Append('%').Append(b.ToString("X2", CultureInfo.InvariantCulture));
}
return sb.ToString();
}
public static string CanonicalUri(Uri uri, bool isS3)
{
var path = string.IsNullOrEmpty(uri.AbsolutePath) ? "/" : uri.AbsolutePath; // already encoded once
return isS3 ? path : string.Join('/', path.Split('/').Select(segment => UriEncode(segment)));
}
public static string CanonicalQuery(Uri uri)
{
var query = uri.Query.TrimStart('?');
if (query.Length == 0) return string.Empty;
return string.Join('&', query.Split('&', StringSplitOptions.RemoveEmptyEntries)
.Select(pair =>
{
var i = pair.IndexOf('=');
var name = Uri.UnescapeDataString(i < 0 ? pair : pair[..i]);
var value = i < 0 ? string.Empty : Uri.UnescapeDataString(pair[(i + 1)..].Replace('+', ' '));
return (Name: UriEncode(name), Value: UriEncode(value));
})
.OrderBy(p => p.Name, StringComparer.Ordinal).ThenBy(p => p.Value, StringComparer.Ordinal)
.Select(p => $"{p.Name}={p.Value}"));
}
public static (string Canonical, string SignedHeaders) Build(string method, Uri uri,
SortedDictionary<string, string> headers, string payloadHash, bool isS3 = false)
{
var canonicalHeaders = string.Concat(headers.Select(h => $"{h.Key}:{CollapseSpaces(h.Value.Trim())}\n"));
var signedHeaders = string.Join(';', headers.Keys);
var canonical = string.Join('\n', method.ToUpperInvariant(), CanonicalUri(uri, isS3), CanonicalQuery(uri),
canonicalHeaders, signedHeaders, payloadHash);
return (canonical, signedHeaders);
}
private static string CollapseSpaces(string value) =>
string.Join(' ', value.Split(' ', StringSplitOptions.RemoveEmptyEntries));
}
public sealed class SigV4Signer(TimeProvider time)
{
public async Task<SigningResult> SignAsync(HttpRequestMessage request, AwsCredentials credentials,
string region, string service, CancellationToken ct = default)
{
var uri = request.RequestUri ?? throw new ArgumentException("RequestUri is required.", nameof(request));
var now = time.GetUtcNow();
var amzDate = now.ToString("yyyyMMdd'T'HHmmss'Z'", CultureInfo.InvariantCulture);
var dateStamp = now.ToString("yyyyMMdd", CultureInfo.InvariantCulture);
var body = request.Content is null ? [] : await request.Content.ReadAsByteArrayAsync(ct);
var payloadHash = Convert.ToHexStringLower(SHA256.HashData(body));
var headers = new SortedDictionary<string, string>(StringComparer.Ordinal)
{
["host"] = uri.IsDefaultPort ? uri.Host : $"{uri.Host}:{uri.Port}",
["x-amz-date"] = amzDate,
};
if (request.Content?.Headers.ContentType is { } contentType) headers["content-type"] = contentType.ToString();
if (credentials.SessionToken is { } token) headers["x-amz-security-token"] = token;
var (canonical, signedHeaders) = CanonicalRequest.Build(request.Method.Method, uri, headers, payloadHash,
isS3: service == "s3");
var scope = $"{dateStamp}/{region}/{service}/aws4_request";
var stringToSign = string.Join('\n', "AWS4-HMAC-SHA256", amzDate, scope,
Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(canonical))));
var key = SigningKey.Derive(credentials.SecretAccessKey, dateStamp, region, service);
var signature = Convert.ToHexStringLower(HMACSHA256.HashData(key, Encoding.UTF8.GetBytes(stringToSign)));
request.Headers.Remove("X-Amz-Date");
request.Headers.TryAddWithoutValidation("X-Amz-Date", amzDate);
if (credentials.SessionToken is { } t)
{
request.Headers.Remove("X-Amz-Security-Token");
request.Headers.TryAddWithoutValidation("X-Amz-Security-Token", t);
}
request.Headers.Remove("Authorization");
request.Headers.TryAddWithoutValidation("Authorization",
$"AWS4-HMAC-SHA256 Credential={credentials.AccessKeyId}/{scope}, SignedHeaders={signedHeaders}, Signature={signature}");
return new SigningResult(canonical, stringToSign, signature);
}
}using System.Text;
using System.Xml.Linq;
using Amazon;
using Amazon.Runtime.CredentialManagement;
using Amazon.SecurityToken;
using Amazon.SecurityToken.Model;
using Harbourline.SigV4;
// 1. Resolve temporary credentials from the SSO profile (needs AWSSDK.SSO + AWSSDK.SSOOIDC).
if (!new CredentialProfileStoreChain().TryGetAWSCredentials("learn-sandbox", out var sdkCredentials))
throw new InvalidOperationException("Profile learn-sandbox not found. Run: aws sso login --profile learn-sandbox");
var keys = await sdkCredentials.GetCredentialsAsync();
var credentials = new AwsCredentials(keys.AccessKey, keys.SecretKey, keys.UseToken ? keys.Token : null);
// 2. Build and hand-sign POST https://sts.us-east-1.amazonaws.com/
using var request = new HttpRequestMessage(HttpMethod.Post, "https://sts.us-east-1.amazonaws.com/")
{
Content = new StringContent("Action=GetCallerIdentity&Version=2011-06-15", Encoding.UTF8, "application/x-www-form-urlencoded"),
};
var signed = await new SigV4Signer(TimeProvider.System).SignAsync(request, credentials, "us-east-1", "sts");
Console.WriteLine($"--- Canonical request ---\n{signed.CanonicalRequest}\n--- String to sign ---\n{signed.StringToSign}");
using var http = new HttpClient();
using var response = await http.SendAsync(request);
var xml = XDocument.Parse(await response.Content.ReadAsStringAsync());
if (!response.IsSuccessStatusCode) throw new InvalidOperationException($"STS returned {(int)response.StatusCode}: {xml}");
XNamespace ns = "https://sts.amazonaws.com/doc/2011-06-15/";
var handSignedArn = xml.Descendants(ns + "Arn").Single().Value;
// 3. Same call through the SDK.
using var sts = new AmazonSecurityTokenServiceClient(sdkCredentials, RegionEndpoint.USEast1);
var sdkArn = (await sts.GetCallerIdentityAsync(new GetCallerIdentityRequest())).Arn;
Console.WriteLine($"Hand-signed: {handSignedArn}\nSDK: {sdkArn}\nMatch: {handSignedArn == sdkArn}");using Amazon.CloudWatchLogs;
using Amazon.CloudWatchLogs.Model;
using Amazon.SecurityToken;
namespace Harbourline.Platform;
public static class AwsSetup
{
public static IServiceCollection AddHarbourlineAws(this IServiceCollection services, IConfiguration config)
{
services.AddDefaultAWSOptions(config.GetAWSOptions()); // reads the "AWS" section: Profile, Region, ...
services.AddAWSService<IAmazonSecurityTokenService>();
services.AddAWSService<IAmazonCloudWatchLogs>();
return services;
}
public static async Task<IReadOnlyList<string>> ListLabLogGroupsAsync(IAmazonCloudWatchLogs logs, CancellationToken ct)
{
var names = new List<string>();
var paginator = logs.Paginators.DescribeLogGroups(new DescribeLogGroupsRequest { LogGroupNamePrefix = "/hl/m04/" });
await foreach (var group in paginator.LogGroups.WithCancellation(ct))
names.Add(group.LogGroupName);
return names;
}
}Code explained line by line
SigningKey.Derive— the four-step HMAC chain; the secret is used only as input to the first HMAC, prefixed withAWS4.UriEncode— encodes every UTF-8 byte except the unreserved set, with uppercase hex.Uri.EscapeDataStringis close but not guaranteed identical, so the lab writes its own as AWS recommends.CanonicalUri(uri, isS3)—AbsolutePathis already encoded once; non-S3 services encode each segment again, S3 does not.CanonicalQuery— decode, re-encode, then sort by name and value with ordinal comparison (culture-aware sorting would differ for some characters).SortedDictionarywithStringComparer.Ordinal— headers in the exact order AWS expects;SignedHeadersfalls out of the keys.CollapseSpaces(h.Value.Trim())— the whitespace normalisation the Harbourline proxy incident broke.Convert.ToHexStringLower— .NET 9+ lowercase hex, the format SigV4 requires.ReadAsByteArrayAsync— the body is hashed exactly as it will be sent.contentType.ToString()— signs the header valueHttpClientwill put on the wire (application/x-www-form-urlencoded; charset=utf-8).x-amz-security-tokenin the canonical headers — required with temporary credentials.scope—date/region/service/aws4_request; any mismatch produces a specific "Credential should be scoped..." error.TryAddWithoutValidation("Authorization", ...)— avoids .NET's header parser reformatting the value.CredentialProfileStoreChain().TryGetAWSCredentials— reads~/.aws/config; for an SSO profile it returns credentials that refresh through IAM Identity Center.keys.UseToken— true for temporary credentials, so the session token is passed on.XDocumentand the STS namespace — STS's Query API responds in XML.AmazonSecurityTokenServiceClient(sdkCredentials, RegionEndpoint.USEast1)— the SDK path with the same credentials; matching ARNs prove the signer is correct.AddDefaultAWSOptions/AddAWSService<T>()— singleton clients configured fromIConfiguration.Paginators.DescribeLogGroups(...).LogGroups— key results asIAsyncEnumerable; the SDK followsNextTokenfor you.
Run the lab
Follow the SigV4 signer lab. Unit tests check the signing key against AWS's documented vector (f4780e2d...b404d for date 20120215, us-east-1, iam) and the canonical requests of the published test suite (get-vanilla, get-vanilla-query-order-key-case, post-x-www-form-urlencoded and others). The real STS call runs only when RUN_AWS_TESTS=1.
Security considerations
⚠ Learning shortcut — not for production
The demo prints the canonical request and string to sign. They contain no secret, but they do include the session token if you sign it, and a session token is a credential. Never log it in production. In production code use the SDK (or its signer) rather than a hand-written one; the lab signer exists to teach and debug.
- No long-lived access keys. Locally use SSO; in AWS use roles. If a tool "cannot find credentials", fix the chain (packages, profile,
AWS_PROFILE), never paste keys. - Clock discipline. SigV4 depends on accurate UTC; containers inherit host time, so keep NTP healthy.
GetCallerIdentityneeds no permission — it works even if explicitly denied — so it is a safe smoke test, but its success proves only authentication, not authorisation.- Presigned URLs are bearer tokens: anyone with the URL can use it until it expires. Keep expiry short for statements containing personal data.
Banking use case
Harbourline's reconciliation service on Fargate reads statement files from S3 and posts results to an IAM-authorised private API Gateway API. The SDK signs S3 calls with the task role's credentials. For the private API (not an SDK service), the team signs requests with a DelegatingHandler built on the same algorithm, service name execute-api — the topic of the next lesson. When the proxy incident recurs, engineers compare the canonical request their code logged (without the token) with the one quoted in AWS's error, and find the modified header in minutes.
Common mistakes
- Missing
AWSSDK.SSO/AWSSDK.SSOOIDC→ SSO profile fails at runtime → add both packages. - Iterating a null collection after upgrading to v4 →
NullReferenceException→ null-check or use paginators. - Reusing a paginator → it yields nothing the second time → create a new one.
ClientConfig.Timeoutfor async calls → ignored → use aCancellationToken.- Signing
+for spaces in query strings → mismatch →%20. - Culture-sensitive sorting of headers/query → mismatch on some machines → ordinal.
- Signing headers a proxy rewrites (
user-agent,connection) → intermittent failures → sign only what is stable.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
SignatureDoesNotMatch / "The request signature we calculated does not match" | Canonical request differs: encoding, header value, body changed after signing, proxy rewrite | Log your canonical request; compare with AWS's; sign after the body is final |
| "Signature expired" / "Signature not yet current" | Clock skew beyond the allowed window (usually 5 minutes) | Sync time (NTP); sign immediately before sending |
| "Credential should be scoped to a valid Region" | Region in scope differs from the endpoint | Use the endpoint's Region |
| "Credential should be scoped to correct service" | Wrong service name (for example apigateway instead of execute-api) | Use the signing name of the endpoint |
Missing Authentication Token | Request not signed, or wrong path on API Gateway | Sign it; check the URL |
IncompleteSignature / "Authorization header requires 'Signature'" | Malformed Authorization value | Check commas and spacing; avoid header reformatting |
ExpiredToken / InvalidClientTokenId | Session expired or token not sent | aws sso login; send X-Amz-Security-Token |
| SSO profile "not found" in .NET but works in CLI | Missing SSO packages, or AWSProfilesLocation overridden | Add AWSSDK.SSO and AWSSDK.SSOOIDC; check config path |
Cost and cleanup
Free. IAM, IAM Identity Center and AWS STS are offered at no additional charge, so GetCallerIdentity costs nothing, and the lab creates no resources. If you created an S3 bucket for the presign example, delete it:
aws s3 rb s3://hl-m04-sigv4-demo-REPLACE --force --profile learn-sandbox
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab \
--profile learn-sandbox --region us-east-1Exercises
- 🟢 Guided: Run the demo, then change one character of the body after signing and observe the error. Restore it, change a signed header value instead, and compare the error messages.
- 🟡 Challenge: Add presigned-URL support (
SignQueryAsync) to the signer for S3GetObjectwithX-Amz-Expires=300andUNSIGNED-PAYLOAD, and verify it againstaws s3 presignoutput structure. - 🔴 Live problem: "Our signer works for
GET /v1/accountson our IAM-authorised API but fails forGET /v1/accounts/ACC-0000123456/statements?from=2026-10-01&to=2026-10-31&status=pending%20review." Find the likely bug(s).
Assignment
Publish your SigV4 signer to your portfolio repo with: passing tests against at least five AWS test-suite vectors, a README diagram of the four signing steps, and a short "debugging SignatureDoesNotMatch" checklist you would give a colleague.
Solutions
Changing the body after signing changes its SHA-256, so the canonical request AWS computes differs and STS returns SignatureDoesNotMatch. Changing a signed header does the same. Changing an unsigned header (for example User-Agent) does not break the signature. Why: only what is in the canonical request is protected — which is also why you sign every header whose integrity matters.
Build the canonical request with X-Amz-Algorithm, X-Amz-Credential (URL-encoded, so / becomes %2F), X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders=host (and X-Amz-Security-Token for temporary credentials) as query parameters, payload UNSIGNED-PAYLOAD, path encoded once (S3). Append X-Amz-Signature. Why: presigned URLs move authentication into the query string so a browser can use them without headers.
Likely causes: (1) the query string is not sorted (from, status, to is the correct order), (2) %20 is decoded to a space and re-encoded as +, or not re-encoded at all, and (3) for execute-api the path segments must be encoded again on top of their existing encoding. Fix by decoding each name and value, re-encoding with the strict UriEncode, sorting ordinally, and applying the non-S3 path rule. Why: simple URLs hide encoding bugs that only appear with spaces, reserved characters and multiple parameters.
Knowledge check
Answer: So a derived key or signature is useless outside that scope. Compromise of a signing key for sts in us-east-1 today does not allow signing S3 requests or requests tomorrow, and the secret access key never leaves the client.
Answer: host (or :authority for HTTP/2) and every x-amz-* header you send (such as x-amz-date and x-amz-security-token). Signing content-type and other meaningful headers is recommended.
Answer: Most likely AWSSDK.SSO and AWSSDK.SSOOIDC are not referenced (v4 requires them for SSO resolution) or the SSO session has expired (aws sso login).
Answer: ECDSA P-256 asymmetric signing with a key pair derived from the secret; the credential scope has no Region; X-Amz-Region-Set lists the Regions the signature is valid in. Used for multi-Region features.
Answer: X-Amz-Expires accepts up to 604,800 seconds (seven days), but with temporary credentials the URL stops working when the session expires.
Interview questions
- Explain SigV4 in one minute. Canonicalise the request, hash it, build a string to sign with timestamp and scope, derive a scoped key from the secret by chained HMACs, HMAC the string, send the signature and scope in
Authorization; AWS recomputes and compares. - How does the .NET SDK find credentials? An ordered chain: explicit, environment variables, web identity, profiles, container credentials, EC2 instance metadata (IMDSv2 only in v4).
- What broke when you moved to SDK v4? Null collections, nullable value types, STS regional endpoints, removed legacy types; SSO needs extra packages.
- How do you debug
SignatureDoesNotMatch? Compare your canonical request with AWS's, check encoding, header values, body changes after signing, and proxies. - When would you sign by hand? Almost never in production — for non-SDK clients, unusual protocols, or to debug. Prefer the SDK's signer.
Certification practice
A .NET 10 API on Amazon ECS on Fargate must read from DynamoDB. A developer proposes storing an IAM user's access key in an environment variable. What is the MOST secure approach that requires no code changes to credential handling?
A. Store the access key in Secrets Manager and read it at startup. B. Assign an IAM task role with least-privilege DynamoDB permissions; the SDK's default credential chain picks up container credentials automatically. C. Bake the key into the container image. D. Use the root user's access key.
Answer: B. Task roles deliver short-lived, rotated credentials through the container credential provider, which the SDK chain uses automatically. A still uses a long-lived key. C and D are insecure.
A service signs requests to an IAM-authorised API. Requests fail with "Signature expired" only on one container host. What is the MOST likely cause?
A. The IAM policy is missing execute-api:Invoke.
B. The host's clock has drifted beyond the allowed window around the request timestamp.
C. The API Gateway stage is throttling.
D. The body is not URL-encoded.
Answer: B. Expiry errors relate to time, and failures limited to one host point to its clock. A gives AccessDenied/403 with a different message. C returns 429. D would produce SignatureDoesNotMatch.
A security engineer wants a smoke test in a deployment pipeline that confirms which role the pipeline is running as, without granting any extra permissions. Which call fits?
A. iam:GetUser
B. sts:GetCallerIdentity
C. iam:ListRoles
D. sts:AssumeRole into the same role
Answer: B. GetCallerIdentity requires no permissions and returns the ARN, account and user id. A and C need IAM permissions and reveal more than needed. D requires a trust policy and creates a new session.
Completion checklist
- I can explain the SDK credential chain and why SSO needs two extra packages
- I handle v4 null collections and use paginators
- I can write out the canonical request and string to sign for a simple POST
- My signer reproduces the documented signing-key vector
- The demo's hand-signed ARN matches the SDK's ARN
- I confirmed nothing tagged
Project=cea-labremains
Key takeaways
- Use the SDK v4 with DI, roles in AWS and SSO locally; never long-lived keys.
- v4 changed defaults: null collections, nullable value types, Standard retry mode, regional STS.
- SigV4 = canonical request → string to sign → scoped signing key → HMAC signature →
Authorization. - Most signature failures are canonicalisation differences: encoding, sorting, whitespace, changed bodies, or clock skew.
- Hand-signing is for understanding and debugging; production code uses the SDK.
Further reading
- AWS Signature Version 4 for API requests
- Create a signed AWS API request
- Elements of an AWS API request signature and authentication methods
- Troubleshoot Signature Version 4 signing
- Migrating to version 4 of the AWS SDK for .NET
- Credential and profile resolution (SDK for .NET v4)
- Using AWSSDK.Extensions.NETCore.Setup and paginators
- STS GetCallerIdentity
- AWS signing test suite (aws-c-auth)
Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.
API keys, usage plans, throttling and rate limiting
Use API Gateway throttling, usage plans and API keys for what they are good at — metering and protecting capacity — add per-customer limits in ASP.NET Core, and handle 429s correctly on the client.
Service-to-service communication: IAM auth, private APIs and service discovery
Connect Harbourline's internal services securely on AWS: choose between private API Gateway, VPC Lattice, ECS Service Connect and events, sign calls with IAM from C#, discover services with Cloud Map, and propagate customer context without trusting it blindly.