Skip to content

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 for requests and httpx that 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
pip install "aws-lambda-powertools[auth-sigv4a]"

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
import os

import requests

from aws_lambda_powertools.utilities.auth import SigV4Signer
from aws_lambda_powertools.utilities.typing import LambdaContext

ORDERS_API = os.environ["ORDERS_API_URL"]  # API Gateway REST API with IAM authorization

# Region and credentials come from the Lambda execution environment
orders_api = SigV4Signer(service="execute-api")
http = requests.Session()
http.auth = orders_api.requests_auth()  # every request through this session is signed


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    response = http.post(f"{ORDERS_API}/orders", json={"customer_id": event["customer_id"]}, timeout=5)
    response.raise_for_status()
    return response.json()

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
import os

import httpx

from aws_lambda_powertools.utilities.auth import SigV4Signer
from aws_lambda_powertools.utilities.typing import LambdaContext

FUNCTION_URL = os.environ["PRICING_FUNCTION_URL"]  # Lambda Function URL with AWS_IAM auth

pricing = SigV4Signer(service="lambda")
client = httpx.Client(base_url=FUNCTION_URL, auth=pricing.httpx_auth(), timeout=5)


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    response = client.get("/quote", params={"sku": event["sku"], "qty": event["qty"]})
    response.raise_for_status()
    return response.json()

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
import json
import os

import urllib3

from aws_lambda_powertools.utilities.auth import SigV4Signer
from aws_lambda_powertools.utilities.typing import LambdaContext

APPSYNC_URL = os.environ["APPSYNC_URL"]  # AppSync GraphQL endpoint with IAM authorization

appsync = SigV4Signer(service="appsync")
http = urllib3.PoolManager()


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    body = json.dumps({"query": "query { getOrder(id: $id) { status } }", "variables": {"id": event["order_id"]}})

    # sign() never sends anything; use the signed URL, headers and body with any HTTP client
    signed = appsync.sign("POST", APPSYNC_URL, headers={"content-type": "application/json"}, body=body)
    response = http.request(signed.method, signed.url, headers=signed.headers, body=signed.body, timeout=5)
    return json.loads(response.data)

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
import os
from urllib.parse import quote

import requests

from aws_lambda_powertools.utilities.auth import SigV4Signer
from aws_lambda_powertools.utilities.typing import LambdaContext

BUCKET = os.environ["REPORTS_BUCKET"]

# service="s3" applies the S3 canonical URI rules, so keys with spaces or "+" sign correctly
s3 = SigV4Signer(service="s3")


def lambda_handler(event: dict, context: LambdaContext) -> str:
    url = f"https://{BUCKET}.s3.{s3.region}.amazonaws.com/{quote(event['key'])}"
    response = requests.get(url, auth=s3.requests_auth(), timeout=5)
    response.raise_for_status()
    return response.text

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
import botocore.session

from aws_lambda_powertools.utilities.auth import SigV4Signer

# Outside Lambda the environment variables may be missing; let botocore's provider chain
# find credentials (profile, SSO, instance role) and name the region explicitly.
signer = SigV4Signer(
    service="execute-api",
    region="eu-west-1",
    session=botocore.session.get_session(),
)

signed = signer.sign("GET", "https://abc123.execute-api.eu-west-1.amazonaws.com/prod/orders")
print(signed.headers["Authorization"])

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
import os

import requests

from aws_lambda_powertools.utilities.auth import SigV4aSigner
from aws_lambda_powertools.utilities.typing import LambdaContext

MRAP_ALIAS = os.environ["MRAP_ALIAS"]  # S3 Multi-Region Access Point alias

# One ECDSA signature valid in both regions; needs pip install "aws-lambda-powertools[auth-sigv4a]"
s3_global = SigV4aSigner(service="s3", region_set=["us-east-1", "eu-west-1"])


def lambda_handler(event: dict, context: LambdaContext) -> str:
    url = f"https://{MRAP_ALIAS}.accesspoint.s3-global.amazonaws.com/{event['key']}"
    response = requests.get(url, auth=s3_global.requests_auth(), timeout=5)
    response.raise_for_status()
    return response.text

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
import json

import requests


def test_orders_call_is_signed(monkeypatch):
    # GIVEN the Lambda environment
    monkeypatch.setenv("AWS_REGION", "us-east-1")
    monkeypatch.setenv("AWS_ACCESS_KEY_ID", "AKIAEXAMPLE")
    monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "example")  # noqa: S105 test value
    monkeypatch.setenv("ORDERS_API_URL", "https://abc123.execute-api.us-east-1.amazonaws.com/prod")

    from requests_client import http, lambda_handler

    sent = {}

    def fake_send(self, request, **kwargs):
        sent["request"] = request
        response = requests.Response()
        response.status_code = 200
        response._content = json.dumps({"order_id": "o-1"}).encode()
        return response

    monkeypatch.setattr(requests.Session, "send", fake_send)

    # WHEN the handler calls the API
    assert lambda_handler({"customer_id": "c-9"}, {}) == {"order_id": "o-1"}

    # THEN the request left with a SigV4 signature over the JSON body
    request = sent["request"]
    assert request.headers["Authorization"].startswith("AWS4-HMAC-SHA256 Credential=AKIAEXAMPLE/")
    assert "X-Amz-Date" in request.headers
    assert json.loads(request.body) == {"customer_id": "c-9"}
    assert http.auth is not None