# API Key Rotator for Amazon CloudFront
In many architectures using Amazon [CloudFront](https://aws.amazon.com/cloudfront/) with [API Gateway](https://aws.amazon.com/api-gateway/), an API key is used to secure communication between CloudFront and the origin (API Gateway). This key is typically passed as a custom header in requests from CloudFront to the origin. While this setup enhances security, it's crucial to regularly rotate these API keys to maintain a robust security posture.
This project provides an automated solution for rotating API keys used in CloudFront distributions. It leverages [AWS Lambda](https://aws.amazon.com/lambda/) and [Secrets Manager](https://aws.amazon.com/secrets-manager/) to securely generate, test, and update API keys without manual intervention.
## Why API Key Rotation is Necessary
1. **Limit Exposure**: Regular rotation limits the time an API key is valid, reducing the window of opportunity for potential attackers.
2. **Compliance**: Many security standards and compliance frameworks require periodic rotation of secrets.
3. **Mitigate Risk**: If a key is compromised, rotation ensures it becomes invalid quickly.
## How It Works
The automated rotation process consists of four main steps:
1. **Create Secret**: Generate a new API key and store it as the "AWSPENDING" version in Secrets Manager.
2. **Set Secret**: Update the CloudFront distribution with the new API key.
3. **Test Secret**: Verify that the new API key works by testing it against the origin.
4. **Finish Secret**: Mark the new API key as "AWSCURRENT" in Secrets Manager, completing the rotation.
## Components
1. `exceptions.py`: Defines custom exceptions for the rotation process.
2. `utils.py`: Contains utility functions for interacting with CloudFront, Secrets Manager, and performing key rotation steps.
3. `handler.py`: Implements the Lambda function handler that orchestrates the rotation process.
## Usage
### Prerequisites
- Python 3.10+
- AWS account with appropriate permissions for Lambda, CloudFront, and Secrets Manager
- CloudFront distribution configured with a custom origin header for API key
### Setup
1. Build and deploy a Lambda function that contains the `amazon-cloudfront-api-key-rotator` using your preferred method (e.g., AWS Console, CloudFormation, or Terraform). Function configuration:
- Python version: 3.10+
- Lambda handler: `api_key_rotator.handler.lambda_handler`
- Environment Variables: See "Environment Variables" section below
- Permissions: See "IAM Permissions" section below
2. Configure Secrets Manager to use this Lambda function for rotation.
### Environment Variables
| Variable | Description | Default Value |
|----------|-------------|---------------|
| `CLOUDFRONT_DISTRIBUTION_ID` | ID of the CloudFront distribution to update | None (Required) |
| `HEADER_NAME` | Name of the custom header for the API key | "x-origin-verify" |
| `ORIGIN_URL` | URL of the origin (API Gateway) to test the rotated API key against | None (Required) |
| `SECRET_KEY_NAME` | Key name for storing the API key in Secrets Manager | "HTTP_API_KEY" |
| `SECRET_KEY_LENGTH` | Length of the generated API key | 32 |
### IAM Permissions
Ensure the Lambda function has the necessary permissions to:
1. Manage secrets in AWS Secrets Manager:
- `secretsmanager:GetSecretValue`
- `secretsmanager:PutSecretValue`
- `secretsmanager:DescribeSecret`
- `secretsmanager:UpdateSecretVersionStage`
2. Access and update CloudFront distributions:
- `cloudfront:GetDistribution`
- `cloudfront:GetDistributionConfig`
- `cloudfront:UpdateDistribution`
### Basic Example
Here's a basic example of how to use the rotator in your AWS environment:
1. Create a secret in AWS Secrets Manager with the initial API key:
```json
{
"HTTP_API_KEY": "your-initial-api-key"
}
```
2. Configure the secret to use the Lambda function for rotation.
3. Update your CloudFront distribution to use the custom header (e.g., "x-origin-verify") with the current API key value.
4. The rotation will occur automatically based on the rotation schedule you set in Secrets Manager.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## Disclaimer
This software product is not affiliated with, endorsed by, or sponsored by Amazon Web Services (AWS) or Amazon.com, Inc. The use of the term "AWS" is solely for descriptive purposes to indicate that the software is compatible with AWS services. Amazon Web Services and AWS are trademarks of Amazon.com, Inc. or its affiliates.
Raw data
{
"_id": null,
"home_page": "https://github.com/efficient-solutions/amazon-cloudfront-api-key-rotator",
"name": "amazon-cloudfront-api-key-rotator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Amazon API Gateway, Amazon CloudFront, AWS Lambda, AWS Secrets Manager",
"author": "Efficient Solutions LLC",
"author_email": "contact@efficient.solutions",
"download_url": "https://files.pythonhosted.org/packages/2c/2a/dc6a07b0dc4f6c8dc3bc8ecf34d77b62f01b66c1fe6f188de4611735b5fd/amazon-cloudfront-api-key-rotator-0.1.0.tar.gz",
"platform": null,
"description": "# API Key Rotator for Amazon CloudFront\n\nIn many architectures using Amazon [CloudFront](https://aws.amazon.com/cloudfront/) with [API Gateway](https://aws.amazon.com/api-gateway/), an API key is used to secure communication between CloudFront and the origin (API Gateway). This key is typically passed as a custom header in requests from CloudFront to the origin. While this setup enhances security, it's crucial to regularly rotate these API keys to maintain a robust security posture.\n\nThis project provides an automated solution for rotating API keys used in CloudFront distributions. It leverages [AWS Lambda](https://aws.amazon.com/lambda/) and [Secrets Manager](https://aws.amazon.com/secrets-manager/) to securely generate, test, and update API keys without manual intervention.\n\n## Why API Key Rotation is Necessary\n\n1. **Limit Exposure**: Regular rotation limits the time an API key is valid, reducing the window of opportunity for potential attackers.\n2. **Compliance**: Many security standards and compliance frameworks require periodic rotation of secrets.\n3. **Mitigate Risk**: If a key is compromised, rotation ensures it becomes invalid quickly.\n\n## How It Works\n\nThe automated rotation process consists of four main steps:\n\n1. **Create Secret**: Generate a new API key and store it as the \"AWSPENDING\" version in Secrets Manager.\n2. **Set Secret**: Update the CloudFront distribution with the new API key.\n3. **Test Secret**: Verify that the new API key works by testing it against the origin.\n4. **Finish Secret**: Mark the new API key as \"AWSCURRENT\" in Secrets Manager, completing the rotation.\n\n## Components\n\n1. `exceptions.py`: Defines custom exceptions for the rotation process.\n2. `utils.py`: Contains utility functions for interacting with CloudFront, Secrets Manager, and performing key rotation steps.\n3. `handler.py`: Implements the Lambda function handler that orchestrates the rotation process.\n\n## Usage\n\n### Prerequisites\n\n- Python 3.10+\n- AWS account with appropriate permissions for Lambda, CloudFront, and Secrets Manager\n- CloudFront distribution configured with a custom origin header for API key\n\n### Setup\n\n1. Build and deploy a Lambda function that contains the `amazon-cloudfront-api-key-rotator` using your preferred method (e.g., AWS Console, CloudFormation, or Terraform). Function configuration:\n - Python version: 3.10+\n - Lambda handler: `api_key_rotator.handler.lambda_handler`\n - Environment Variables: See \"Environment Variables\" section below\n - Permissions: See \"IAM Permissions\" section below\n\n2. Configure Secrets Manager to use this Lambda function for rotation.\n\n### Environment Variables\n\n| Variable | Description | Default Value |\n|----------|-------------|---------------|\n| `CLOUDFRONT_DISTRIBUTION_ID` | ID of the CloudFront distribution to update | None (Required) |\n| `HEADER_NAME` | Name of the custom header for the API key | \"x-origin-verify\" |\n| `ORIGIN_URL` | URL of the origin (API Gateway) to test the rotated API key against | None (Required) |\n| `SECRET_KEY_NAME` | Key name for storing the API key in Secrets Manager | \"HTTP_API_KEY\" |\n| `SECRET_KEY_LENGTH` | Length of the generated API key | 32 |\n\n### IAM Permissions\n\nEnsure the Lambda function has the necessary permissions to:\n\n1. Manage secrets in AWS Secrets Manager:\n - `secretsmanager:GetSecretValue`\n - `secretsmanager:PutSecretValue`\n - `secretsmanager:DescribeSecret`\n - `secretsmanager:UpdateSecretVersionStage`\n\n2. Access and update CloudFront distributions:\n - `cloudfront:GetDistribution`\n - `cloudfront:GetDistributionConfig`\n - `cloudfront:UpdateDistribution`\n\n### Basic Example\n\nHere's a basic example of how to use the rotator in your AWS environment:\n\n1. Create a secret in AWS Secrets Manager with the initial API key:\n\n ```json\n {\n \"HTTP_API_KEY\": \"your-initial-api-key\"\n }\n ```\n\n2. Configure the secret to use the Lambda function for rotation.\n\n3. Update your CloudFront distribution to use the custom header (e.g., \"x-origin-verify\") with the current API key value.\n\n4. The rotation will occur automatically based on the rotation schedule you set in Secrets Manager.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\nThis software product is not affiliated with, endorsed by, or sponsored by Amazon Web Services (AWS) or Amazon.com, Inc. The use of the term \"AWS\" is solely for descriptive purposes to indicate that the software is compatible with AWS services. Amazon Web Services and AWS are trademarks of Amazon.com, Inc. or its affiliates.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatic API key rotation for CloudFront with Secrets Manager and Lambda",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/efficient-solutions/amazon-cloudfront-api-key-rotator"
},
"split_keywords": [
"amazon api gateway",
" amazon cloudfront",
" aws lambda",
" aws secrets manager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4bd2e50976bbb3e733182ddf69f13ee5371af12a6bd0c554356800fe7fc717ed",
"md5": "60418529e8ddf6daba392cdcf5f35a53",
"sha256": "4be77cd42f06acbb47d8fee6f8f2a2dd8b17f7ce3b9efcca26b4be37a03f6bbf"
},
"downloads": -1,
"filename": "amazon_cloudfront_api_key_rotator-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60418529e8ddf6daba392cdcf5f35a53",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9146,
"upload_time": "2024-10-20T23:17:30",
"upload_time_iso_8601": "2024-10-20T23:17:30.633325Z",
"url": "https://files.pythonhosted.org/packages/4b/d2/e50976bbb3e733182ddf69f13ee5371af12a6bd0c554356800fe7fc717ed/amazon_cloudfront_api_key_rotator-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2c2adc6a07b0dc4f6c8dc3bc8ecf34d77b62f01b66c1fe6f188de4611735b5fd",
"md5": "0c0970478a4625582cdcccb408331eb1",
"sha256": "7855e15c49604c87849a0e22c06f852b951d012f485e7ccc843e86516e8aa799"
},
"downloads": -1,
"filename": "amazon-cloudfront-api-key-rotator-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0c0970478a4625582cdcccb408331eb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7898,
"upload_time": "2024-10-20T23:17:32",
"upload_time_iso_8601": "2024-10-20T23:17:32.776311Z",
"url": "https://files.pythonhosted.org/packages/2c/2a/dc6a07b0dc4f6c8dc3bc8ecf34d77b62f01b66c1fe6f188de4611735b5fd/amazon-cloudfront-api-key-rotator-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 23:17:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "efficient-solutions",
"github_project": "amazon-cloudfront-api-key-rotator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "amazon-cloudfront-api-key-rotator"
}
JSON
