Skip to Content
Cloud Engineering Academy
4. API Development & Integration

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.

advanced⏱ 2 h 🟢 FreeDVA-C03SCS-C03

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-Date and X-Amz-Security-Token — and say what presigned URLs and SigV4a change.
  • Hand-sign an STS GetCallerIdentity request in C# (Lab 4.5) and compare it with the SDK.
  • Diagnose SignatureDoesNotMatch, clock-skew and encoding errors.

Prerequisites

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

ConcernWhat the SDK v4 doesWhat you still own
CredentialsResolves a chain: explicit → env vars → web identity → profile (AWS_PROFILE / [default]) → container credentials → EC2 instance metadataNever ship access keys; use roles in AWS and SSO locally
RegionFrom client config, AWS_REGION, or profileSet it explicitly in config to avoid surprises
SigningSigV4 (SigV4a automatically for multi-Region features such as S3 Multi-Region Access Points)Keep the clock in sync
RetriesRetryMode defaults to Standard in v4; MaxErrorRetry 2 for most servicesChoose Adaptive for heavy throttling; never stack Polly retries on top
TimeoutsAsync calls honour your CancellationTokenPass a token with a deadline
Paginationclient.Paginators.X(...) returns IAsyncEnumerable resultsCreate 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 equivalentWhat's different
DefaultAzureCredentialSDK default credential chain (DefaultAWSCredentialsIdentityResolver)Similar idea; the AWS chain is ordered differently and uses profiles
az login + developer credentialaws sso login --profile learn-sandbox + SSO profileSDK needs AWSSDK.SSO and AWSSDK.SSOOIDC
Managed identity on App Service / FunctionsIAM role for Lambda (execution role) / ECS task roleCredentials delivered by the platform, rotated automatically
services.AddAzureClients(...)AddDefaultAWSOptions + AddAWSService<T>()Clients registered as singletons by default
Bearer tokens from Entra ID on every callSigV4 signature on every callNo token endpoint; the request itself is signed
SAS URL for Blob StorageS3 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 resultsPaginators 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
ab821ae955788b0e33ebd34c208442ccfc2d406e2edc5e7a39bd6458fbb4f843

Rules that matter:

  • Header names lowercase, sorted; values trimmed with internal runs of spaces collapsed to one. host and every x-amz-* header you send must be signed; signing content-type too is good practice. Do not sign hop-by-hop headers such as connection or user-agent, which proxies change.
  • Query string: URI-encode each name and value separately (%20 for space, never +; uppercase hex; only A–Z a–z 0–9 - . _ ~ unencoded), then sort by name. A parameter with no value is name=.
  • 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 literal UNSIGNED-PAYLOAD (sent in x-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
8fea968c4fc0abd86c9f9a8441a330ac1331418a833e92021ca5cb16c7ed425e

3. 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")
         = 7164e55f62337519e36d022df8bfbcb657bc808e0582cc74873f4df51d9b11cc

4. 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=6be3b8d0c0c50bd9420c9fdc718412530ffb4ed194f23b81eefab27b30c87804

With 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-sandbox

Infrastructure 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.

src/Harbourline.SigV4/SigV4Signer.cs
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);
    }
}
src/Harbourline.SigV4.Demo/Program.cs
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}");
src/Harbourline.Platform/AwsSetup.cs (DI and paginators)
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

  1. SigningKey.Derive — the four-step HMAC chain; the secret is used only as input to the first HMAC, prefixed with AWS4.
  2. UriEncode — encodes every UTF-8 byte except the unreserved set, with uppercase hex. Uri.EscapeDataString is close but not guaranteed identical, so the lab writes its own as AWS recommends.
  3. CanonicalUri(uri, isS3) — AbsolutePath is already encoded once; non-S3 services encode each segment again, S3 does not.
  4. CanonicalQuery — decode, re-encode, then sort by name and value with ordinal comparison (culture-aware sorting would differ for some characters).
  5. SortedDictionary with StringComparer.Ordinal — headers in the exact order AWS expects; SignedHeaders falls out of the keys.
  6. CollapseSpaces(h.Value.Trim()) — the whitespace normalisation the Harbourline proxy incident broke.
  7. Convert.ToHexStringLower — .NET 9+ lowercase hex, the format SigV4 requires.
  8. ReadAsByteArrayAsync — the body is hashed exactly as it will be sent.
  9. contentType.ToString() — signs the header value HttpClient will put on the wire (application/x-www-form-urlencoded; charset=utf-8).
  10. x-amz-security-token in the canonical headers — required with temporary credentials.
  11. scope — date/region/service/aws4_request; any mismatch produces a specific "Credential should be scoped..." error.
  12. TryAddWithoutValidation("Authorization", ...) — avoids .NET's header parser reformatting the value.
  13. CredentialProfileStoreChain().TryGetAWSCredentials — reads ~/.aws/config; for an SSO profile it returns credentials that refresh through IAM Identity Center.
  14. keys.UseToken — true for temporary credentials, so the session token is passed on.
  15. XDocument and the STS namespace — STS's Query API responds in XML.
  16. AmazonSecurityTokenServiceClient(sdkCredentials, RegionEndpoint.USEast1) — the SDK path with the same credentials; matching ARNs prove the signer is correct.
  17. AddDefaultAWSOptions / AddAWSService<T>() — singleton clients configured from IConfiguration.
  18. Paginators.DescribeLogGroups(...).LogGroups — key results as IAsyncEnumerable; the SDK follows NextToken for 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.
  • GetCallerIdentity needs 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.Timeout for async calls → ignored → use a CancellationToken.
  • 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

SymptomLikely causeFix
SignatureDoesNotMatch / "The request signature we calculated does not match"Canonical request differs: encoding, header value, body changed after signing, proxy rewriteLog 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 endpointUse 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 TokenRequest not signed, or wrong path on API GatewaySign it; check the URL
IncompleteSignature / "Authorization header requires 'Signature'"Malformed Authorization valueCheck commas and spacing; avoid header reformatting
ExpiredToken / InvalidClientTokenIdSession expired or token not sentaws sso login; send X-Amz-Security-Token
SSO profile "not found" in .NET but works in CLIMissing SSO packages, or AWSProfilesLocation overriddenAdd 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-1

Exercises

  • 🟢 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 S3 GetObject with X-Amz-Expires=300 and UNSIGNED-PAYLOAD, and verify it against aws s3 presign output structure.
  • 🔴 Live problem: "Our signer works for GET /v1/accounts on our IAM-authorised API but fails for GET /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

Knowledge check

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

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-lab remains

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

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.

On this page