Install & Compatibility
Where this runs
tested against v0.1.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.516s · 53.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.2s · import 0.462s · 54MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AWSV4Sign
✓ from requests_aws_sign import AWSV4Sign
This is the primary class provided for request signing.
This quickstart demonstrates how to use `requests-aws-sign` to sign an HTTP GET request to an AWS service (e.g., Elasticsearch Service). It leverages `boto3` to automatically retrieve AWS credentials and region, falling back to dummy credentials if not found. This ensures the necessary `AWSV4Sign` object is correctly initialized before making the signed request. Remember to replace the `url` and `service` with your actual AWS service endpoint and name.
import requests
from requests_aws_sign import AWSV4Sign
from boto3 import session
import os
# NOTE: For a real application, ensure AWS credentials are set via environment
# variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
# or AWS config files, so boto3 can find them.
# For this example, we'll try to get them, but you might need to set them.
session_boto3 = session.Session()
credentials = session_boto3.get_credentials() if session_boto3.get_credentials() else None
if not credentials or not credentials.access_key or not credentials.secret_key:
print("Warning: AWS credentials not found. Using dummy credentials. This request will likely fail.")
print("Please configure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN environment variables.")
access_key = os.environ.get('AWS_ACCESS_KEY_ID', 'AKIAIOSFODNN7EXAMPLE')
secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY')
session_token = os.environ.get('AWS_SESSION_TOKEN', None)
# Mocking a credentials object if boto3 couldn't find them
class MockCredentials:
def __init__(self, access_key, secret_key, token):
self.access_key = access_key
self.secret_key = secret_key
self.token = token
credentials = MockCredentials(access_key, secret_key, session_token)
region = session_boto3.region_name or 'us-east-1' # Default to us-east-1 if boto3 can't determine
service = 'es' # Example service, e.g., 's3', 'execute-api', 'es'
# This URL is an example and likely won't work without a real Elasticsearch domain
# Replace with a real AWS service endpoint you have access to
url = f"https://{service}-domain-example.{region}.es.amazonaws.com/"
auth = AWSV4Sign(credentials, region, service)
try:
response = requests.get(url, auth=auth, timeout=5) # Added timeout
response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
print(f"Successfully signed and sent request to {url}")
print(f"Status Code: {response.status_code}")
# print(response.text) # Uncomment to see response body
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
if hasattr(e, 'response') and e.response is not None:
print(f"Response status code: {e.response.status_code}")
print(f"Response headers: {e.response.headers}")
print(f"Response body: {e.response.text}")
Debug
Known issues
gotchaAWS SigV4 signing requires specific parameters: valid AWS credentials, the correct AWS region, and the exact AWS service name (e.g., 's3', 'es', 'execute-api'). Incorrect values for any of these parameters will result in 'SignatureDoesNotMatch' or 'IncompleteSignature' errors from AWS services.fixEnsure `credentials`, `region`, and `service` passed to `AWSV4Sign` are accurate for the target AWS endpoint. Use `boto3.session.Session().get_credentials()` and `boto3.session.Session().region_name` to reliably get credentials and region. Consult AWS documentation for the correct service identifier for your API.
affects: All
gotchaWhen using AWS Security Token Service (STS) temporary credentials (e.g., from an assumed role or EC2 instance profile), the `AWSV4Sign` class needs the `session_token` in addition to `access_key` and `secret_key`. Failure to include the `X-Amz-Security-Token` header (which the library adds if `session_token` is provided) will lead to authentication failures like 'ExpiredTokenException'.fixEnsure your credential object (e.g., from `boto3.session.Session().get_credentials()`) correctly provides the `token` attribute if temporary credentials are in use. The `AWSV4Sign` constructor takes this `credentials` object directly, which should contain the `token` if available.
affects: All
gotchaThis library primarily focuses on signing individual `requests` calls. For making multiple signed requests to the same AWS service efficiently, it's generally best practice to use a `requests.Session` object. The `AWSV4Sign` object can be assigned to a session's `auth` attribute, but the library does not provide a specialized `Session` subclass itself.fixTo use with a session: `s = requests.Session(); s.auth = AWSV4Sign(credentials, region, service); response = s.get(url)`. This reuses underlying connections and applies the auth consistently.
affects: All
breakingWhile `requests-aws-sign` itself is designed for SigV4, older AWS SDKs or custom implementations might still use Signature Version 2 (SigV2). AWS has deprecated SigV2 for new S3 buckets created after June 24, 2020, and strongly encourages migration to SigV4 for all services due to enhanced security. If you are integrating with an existing system that uses SigV2, this library will not be compatible.fixEnsure all AWS services you interact with support or require Signature Version 4. This library exclusively generates SigV4 signatures. Migrate any legacy SigV2 implementations to SigV4. The AWS SDKs handle this automatically with up-to-date versions.
affects: N/A (issue is with AWS, not this library, but affects its applicability)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'requests_aws_sign'
The 'requests-aws-sign' package has not been installed or is not accessible in the current Python environment.
fixpip install requests-aws-sign
botocore.exceptions.NoCredentialsError: Unable to locate credentials
`requests-aws-sign` (which uses `botocore` internally) could not find AWS credentials through standard methods like environment variables, shared credential files, or an explicitly provided `credentials` object.
fixConfigure AWS credentials using environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), a shared credentials file (`~/.aws/credentials`), or pass a `botocore.credentials.Credentials` object directly to `AWSV4Sign`.
The request signature we calculated does not match the signature you provided. Check your AWS Secret Access Key and signing method.
This error (often accompanied by an HTTP 403 Forbidden status from AWS) indicates that the parameters used by `AWSV4Sign` to sign the request (e.g., region, service, host, or the underlying credentials) are incorrect or do not match what AWS expects for the given request.
fixVerify that `AWSV4Sign` is initialized with the correct `aws_region`, `aws_service`, `aws_host` (if specified), and that the AWS credentials used are valid and have the necessary permissions for the target service and action.
Upgrade
Version history
0.1.6latest on PyPI · released Jul 5, 2020
Audit
Dependencies
requestsrequiredCore HTTP library that requests-aws-sign extends for authentication.
boto3optionalHighly recommended for robust AWS credential management (e.g., fetching credentials from environment variables, IAM roles, or STS temporary credentials), though not a strict runtime dependency of the signing logic itself.