AWS Requests Auth

0.4.3 · active · verified Sat Apr 11

aws-requests-auth (version 0.4.3) is a Python library that implements the AWS Signature Version 4 signing process for the popular `requests` module. It enables authentication to AWS services that support Signature Version 4, originally designed for AWS Elasticsearch instances but extensible to other services. The library has been stable since its last release in May 2020.

Common errors

```
SignatureDoesNotMatch
```
cause The request signature doesn't conform to AWS standards.

fix Ensure that your AWS Secret Access Key is correctly configured and that the 'sts_region' matches the AWS region where your IAM roles are deployed.
```
AccessDeniedException
```
cause You don't have sufficient access to perform this action.

fix Verify that your IAM policy includes the required permissions.
```
ExpiredTokenException
```
cause The security token included in the request is expired.

fix Request a new security token and try again.
```
IncompleteSignature
```
cause The request signature doesn't conform to AWS standards.

fix Verify that you're using valid AWS credentials and that your request is properly formatted.
```
UnrecognizedClientException
```
cause The AWS access key ID provided does not exist in our records.

fix Verify that you're using valid credentials and that they haven't expired.

Warnings

gotcha Incorrect or expired AWS credentials (access key, secret key, session token) or an invalid combination of host, region, and service are common causes of authentication failures. AWS will respond with errors like `InvalidClientTokenId` or `SignatureDoesNotMatch` if the request cannot be authenticated.
Fix: Double-check that `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `aws_host`, and `aws_service` are correctly configured. If using STS temporary credentials, ensure `AWS_SESSION_TOKEN` is provided via the `aws_token` argument.
gotcha When deploying applications using `aws-requests-auth` to serverless environments (e.g., AWS Lambda), ensure the library, along with its dependencies (like `requests`), is correctly bundled in your deployment package. Failure to do so can result in `Runtime.ImportModuleError` (e.g., `No module named 'aws_requests_auth'`).
Fix: Include `aws-requests-auth` and its dependencies in your `requirements.txt` and ensure your build process (e.g., `sam build` for AWS SAM) correctly packages them.
gotcha If using the `BotoAWSRequestsAuth` class for automatic credential retrieval, `botocore` is an optional dependency that must be installed. Without `botocore`, `BotoAWSRequestsAuth` cannot function and may lead to runtime errors or incorrect credential handling.
Fix: If you intend to use `BotoAWSRequestsAuth`, ensure you install `botocore` explicitly: `pip install botocore`.
gotcha When making requests to AWS services, if the configured endpoint hostname (e.g., `aws_host`) cannot be resolved via DNS, the request will fail with a `NameResolutionError`. This indicates that the system cannot find an IP address for the specified hostname.
Fix: Verify that the `aws_host` (or equivalent endpoint configuration) is spelled correctly and is a valid, resolvable hostname. Check your network configuration and DNS settings to ensure that external hostnames can be resolved from the environment where the application is running.

Install

pip install aws-requests-auth Install with pip

Imports

AWSRequestsAuth
wrong:
```
from aws_requests_auth import AWSRequestsAuth
```
correct:
```
from aws_requests_auth.aws_auth import AWSRequestsAuth
```
The primary authentication class is located within the `aws_auth` submodule.
BotoAWSRequestsAuth
```
from aws_requests_auth.boto_utils import BotoAWSRequestsAuth
```
Used for automatic credential retrieval via botocore, if installed.

Quickstart

This quickstart demonstrates how to use `AWSRequestsAuth` to sign a request to an AWS service endpoint. Replace `your-aws-endpoint.amazonaws.com` and the service-specific path (`/_cat/health`) with your actual AWS service endpoint and path. Credentials are retrieved from environment variables for security and flexibility, with fallbacks for demonstration.

import requests
import os
from aws_requests_auth.aws_auth import AWSRequestsAuth

aws_access_key = os.environ.get('AWS_ACCESS_KEY_ID', 'YOUR_ACCESS_KEY')
aws_secret_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'YOUR_SECRET_KEY')
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
aws_service = 'es' # Example service, e.g., 'es' for Elasticsearch, 's3', 'execute-api'
aws_host = 'your-aws-endpoint.amazonaws.com'

# For STS temporary credentials, include aws_token
aws_token = os.environ.get('AWS_SESSION_TOKEN')

auth = AWSRequestsAuth(
    aws_access_key=aws_access_key,
    aws_secret_access_key=aws_secret_key,
    aws_host=aws_host,
    aws_region=aws_region,
    aws_service=aws_service,
    aws_token=aws_token # Pass if using STS temporary credentials
)

try:
    # Replace with your actual endpoint
    response = requests.get(f'https://{aws_host}/_cat/health', auth=auth, timeout=10)
    response.raise_for_status() # Raise an exception for HTTP errors
    print("Successfully authenticated and received response:")
    print(response.text)
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 Body: {e.response.text}")
    print("Please ensure your AWS credentials, host, region, and service are correct.")

view raw JSON →