Request signing
Sign HTTP requests to IAM-protected AWS endpoints with Signature Version 4, using the botocore the Lambda runtime already ships. Part of the Auth utility, next to JWT verification and the OAuth2 client.
Key features¶
- Sign a request and get back the headers and URL to send, with any HTTP client
- Drop-in
auth=objects forrequestsandhttpxthat sign every call - Region and credentials read from the Lambda environment, no credential provider chain on the cold start path
- S3 canonical rules applied when the service is S3
- SigV4a for multi-region endpoints such as S3 Multi-Region Access Points, behind an optional extra
Getting started¶
Install¶
Nothing to install for SigV4: the signer only needs botocore, which the Lambda runtime provides. If you package your function without the runtime's boto3, add aws-lambda-powertools[aws-sdk].
SigV4a needs the awscrt package, which the runtime does not ship:
1 | |
Sign requests with requests¶
Pass requests_auth() as auth= and every request through that session is signed on the way out. The example calls an API Gateway REST API with IAM authorization; the signing name for API Gateway is execute-api.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | |
Sign requests with httpx¶
httpx_auth() does the same for httpx. This example calls a Lambda Function URL with AWS_IAM auth; the signing name is lambda.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | |
Sign only, send with any client¶
sign() never touches the network. It returns a SignedRequest with the method, the url to send, the headers including Authorization, and the body. Use them with urllib3, a generated client, or anything else.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | |
Send the URL you get back
The query string is re-encoded the way SigV4 canonicalises it (a space becomes %20, repeated keys are kept). Send signed.url, not the URL you passed in, or the signature will not match. The requests and httpx helpers do this for you.
Signing names¶
The service parameter is the signing name of the target, not the hostname. Common ones:
| Target | service |
|---|---|
| API Gateway REST and HTTP APIs | execute-api |
| Lambda Function URLs | lambda |
| AppSync | appsync |
| OpenSearch | es |
| Amazon S3 | s3 |
Advanced¶
Amazon S3¶
Use service="s3". The signer switches to the S3 canonical URI rules, so object keys with spaces, + or other characters that S3 encodes differently from the rest of AWS sign correctly, and the x-amz-content-sha256 header is added.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | |
Credentials and region outside Lambda¶
Inside Lambda, AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN are always set and the signer reads them. Elsewhere, pass region= and either credentials= (a botocore.credentials.Credentials) or session= (a botocore.session.Session, resolved through its provider chain). An explicit credentials= also serves cross-account calls with assumed-role credentials.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | |
SigV4a for multi-region endpoints¶
SigV4aSigner produces an ECDSA signature valid across a set of regions, which S3 Multi-Region Access Points require. Pass the regions in region_set, or "*" for every region. It needs the auth-sigv4a extra.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | |
Errors¶
| Exception | When |
|---|---|
SignerConfigError |
At construction: no region, no credentials, an empty service, or SigV4aSigner without awscrt. The message says which, and never includes credential material. |
TypeError |
A streaming request body was passed to a client helper. Read it into bytes first; SigV4 hashes the whole payload. |
A rejected signature comes back from the service as HTTP 403 with The request signature we calculated does not match. The usual causes are a wrong service name, a wrong region, or a client that changed the request after signing.
Testing your code¶
Sign against fixed environment variables and assert on the headers that leave; the signature algorithm itself is botocore's and does not need testing on your side.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | |