# B.CfnCustomApiKeyAuthorizer
An AWS CDK resource that enables protection of your public APIs by
using Api Keys (ApiKey and Secret).
### Description
This custom authorizer enables Api Key functionality
(something similar to ApiGateway V1 version: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-setup-api-key-with-console.html)
APIs created via ApiGateway V2 do not have Api Key authorization functionality out-of-the-box.
If you want to protect your V2 API by generating a secret key and giving only for the
intended clients - this library is just for you. This library allows you to protect you
ApiGatewayV2-based endpoints with a combination of ApiKey and ApiSecret. Refer to usages & examples
to understand how to use this library.
The authorizer library exposes these lambda functions that can be called directly:
- `authorizer` - _ApiKeysAuthorizerFunction_ - used by a custom (this) authorizer that is attached to your API.
- `deleter` - _ApiKeysDeleterFunction_ - allows revoking access to your API i.e. deletes api keys.
- `exists` - _ApiKeysExistsFunction_ - allows you to check whether a given API key exists in the database.
- `generator` - _ApiKeysGeneratorFunction_ - generates api key and api secret pair and saves in an internal database.
- `validator` - _ApiKeysValidatorFunction_ - validates given api key and api secret against the ones in the database.
### Remarks
[Biomapas](https://www.biomapas.com/) aims to modernise life-science industry by sharing its IT knowledge with other
companies and the community. This is an open source library intended to be used by anyone. Improvements and pull
requests are welcome.
### Related technology
- Python3
- AWS CDK
- AWS CloudFormation
- AWS API Gateway
- AWS API Gateway Authorizer
- AWS Lambda
### Assumptions
This project assumes you are an expert in infrastructure-as-code via AWS CloudFormation and AWS CDK. You must clearly
understand how AWS API Gateway endpoints are protected with Authorizers / Custom Authorizers and how it is managed via
CloudFormation or CDK.
- Excellent knowledge in IaaC (Infrastructure as a Code) principles.
- Excellent knowledge in API Gateway, Authorizers.
- Good experience in AWS CDK and AWS CloudFormation.
- Good Python skills and basics of OOP.
### Useful sources
- AWS CDK:<br>https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html
- AWS CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
- API Gateway with
CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html
- AWS Custom
Authorizers:<br>https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html
### Install
Before installing this library, ensure you have these tools setup:
- Python / Pip
- AWS CDK
To install this project from source run:
```
pip install .
```
Or you can install it from a PyPi repository:
```
pip install b-cfn-custom-api-key-authorizer
```
### Usage & Examples
Firstly, create an api and stage:
```python
from aws_cdk.aws_apigatewayv2 import CfnApi, CfnStage
api = CfnApi(...)
api_stage = CfnStage(...)
```
Create api key custom authorizer:
```python
from b_cfn_custom_api_key_authorizer.custom_authorizer import ApiKeyCustomAuthorizer
from b_cfn_custom_api_key_authorizer.authorization_type import AuthorizationType
authorizer = ApiKeyCustomAuthorizer(
scope=Stack(...),
resource_name_prefix='MyCool',
api=api,
# If you specify this, your API will look for "ApiKey" and "ApiSecret" headers in your request.
# authorization_type=AuthorizationType.API_KEY_AND_SECRET_HEADERS
# If you specify this, your API will treat your request with basic auth in mind ("Authorization" header).
# authorization_type=AuthorizationType.AUTHORIZATION_HEADER
)
```
Use that authorizer to protect your routes (endpoints):
```python
from aws_cdk.aws_apigatewayv2 import CfnRoute
route = CfnRoute(
scope=Stack(...),
id='DummyRoute',
api_id=api.ref,
route_key='GET /dummy/endpoint',
authorization_type='CUSTOM',
target=f'integrations/{integration.ref}',
authorizer_id=authorizer.ref
)
```
Once your infrastructure is deployed, try calling your api endpoint. You will get "Unauthorized" error.
```python
import urllib3
response = urllib3.PoolManager().request(
method='GET',
url='https://your-api-url/dummy/endpoint',
headers={},
)
>>> response.status
>>> 401
```
Create `ApiKey` and `ApiSecret` by invoking a dedicated api keys generator lambda function:
```python
# Your supplied prefix for the infrastrucutre.
resource_name_prefix = 'MyCool'
# Created generator lambda function name.
function_name = 'ApiKeysGeneratorFunction'
# Full function name is a combination of both.
function_name = resource_name_prefix + function_name
response = boto3.client('lambda').invoke(
FunctionName=function_name,
InvocationType='RequestResponse',
)
response = json.loads(response['Payload'].read())
api_key = response['ApiKey']
api_secret = response['ApiSecret']
```
Now try calling the same api with api keys:
```python
import urllib3
response = urllib3.PoolManager().request(
method='GET',
url='https://your-api-url/dummy/endpoint',
headers={
'ApiKey': api_key,
'ApiSecret': api_secret
},
)
>>> response.status
>>> 200
```
#### Exposed lambda functions
The authorizer exposes these lambda functions that can be called directly:
- `authorizer` - ApiKeysAuthorizerFunction
```python
response = boto3.client('lambda').invoke(
FunctionName=prefix + 'ApiKeysAuthorizerFunction',
InvocationType='RequestResponse',
Payload=json.dumps({
'ApiKey': '123',
'ApiSecret': '123'
}).encode()
)
response = json.loads(response['Payload'].read())
# This will contain a dictionary of IAM based
# permission either to "allow" or "deny" the request.
print(response)
```
- `deleter` - ApiKeysDeleterFunction
```python
# This does not produce a response.
boto3.client('lambda').invoke(
FunctionName=prefix + 'ApiKeysDeleterFunction',
InvocationType='RequestResponse',
Payload=json.dumps({
'ApiKey': '123',
}).encode()
)
```
- `exists` - ApiKeysExistsFunction
```python
response = boto3.client('lambda').invoke(
FunctionName=prefix + 'ApiKeysExistsFunction',
InvocationType='RequestResponse',
Payload=json.dumps({
'ApiKey': '123',
}).encode()
)
response = json.loads(response['Payload'].read())
# Check whether your ApiKey/Secret exists in the database.
assert response['Exists'] is True
```
- `generator` - ApiKeysGeneratorFunction
```python
response = boto3.client('lambda').invoke(
FunctionName=prefix + 'ApiKeysGeneratorFunction',
InvocationType='RequestResponse',
)
response = json.loads(response['Payload'].read())
api_key = response['ApiKey']
api_secret = response['ApiSecret']
```
- `validator` - ApiKeysValidatorFunction
```python
response = boto3.client('lambda').invoke(
FunctionName=prefix + 'ApiKeysValidatorFunction',
InvocationType='RequestResponse',
Payload=json.dumps({
'ApiKey': '123',
'ApiSecret': '123',
}).encode()
)
response = json.loads(response['Payload'].read())
# Check whether your ApiKey/Secret is valid.
assert response['Valid'] is True
```
### Testing
This package has integration tests based on **pytest**. To run tests simply run:
```
pytest b_cfn_custom_api_key_authorizer_test/integration/tests
```
### Contribution
Found a bug? Want to add or suggest a new feature? Contributions of any kind are gladly welcome. You may contact us
directly, create a pull-request or an issue in github platform. Lets modernize the world together.
# Release history
### 3.0.0
* Upgrade CDK support from v1 to v2.
* Upgrade GitHub pipelines checkout version from v2 to v3.
* Set GitHub pipelines node version 18.
* Set GitHub pipelines python version 3.10.
### 2.3.0
* Update of `authorizer` function. Removing of sensitive information form lambda event implemented.
### 2.2.0
* Remove unnecessary dependencies.
### 2.1.1
* Add more integration tests.
* Update README documentation.
### 2.1.0
* Add ability to specify what type of authentication strategy to use.
Support for both `ApiKey` / `ApiSecret` and `Authorization` headers.
### 2.0.1
* Dollar sign excluded from API secret.
### 2.0.0
* Restructured project.
* All lambda functions are under `functions` directory.
* Add `deleter` function to revoke api keys.
* Add `exists` function to check whether given api key exists.
* Add `validator` function to validate api key and api secret.
* Increase the length of api key (15) and api secret (30).
* Move authentication checking logic to a lambda layer.
* Add more lambda-level logging.
* Add more integrations tests (total 11 as of now).
* **Very important security improvement** - api secrets are now hashed, to avoid
leaks if the database is pawned. This is a standard password-level storage security.
* Greatly improve documentation.
### 1.1.0
* Create a dedicated lambda function to generate
api keys. You should not interact with the database directly.
### 1.0.0
* Prod-ready version.
* Added documentation.
* Added more tests.
* Some code improvements.
### 0.1.0
* Initial testing done. Authorizer works.
* Need more tests and edge case handling before promoting to 1.0.0.
### 0.0.1
* Initial build.
Raw data
{
"_id": null,
"home_page": "https://github.com/biomapas/B.CfnCustomApiKeyAuthorizer.git",
"name": "b-cfn-custom-api-key-authorizer",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "AWS Cognito api_key Authorizer",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/8e/0e/9c09bfdd83027b60634ebd807acee84d5a8dbe9734fca56d6f04b2ec497b/b_cfn_custom_api_key_authorizer-3.0.0.tar.gz",
"platform": null,
"description": "# B.CfnCustomApiKeyAuthorizer\n\n\n\nAn AWS CDK resource that enables protection of your public APIs by \nusing Api Keys (ApiKey and Secret).\n\n### Description\n\nThis custom authorizer enables Api Key functionality \n(something similar to ApiGateway V1 version: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-setup-api-key-with-console.html)\n\nAPIs created via ApiGateway V2 do not have Api Key authorization functionality out-of-the-box. \nIf you want to protect your V2 API by generating a secret key and giving only for the \nintended clients - this library is just for you. This library allows you to protect you\nApiGatewayV2-based endpoints with a combination of ApiKey and ApiSecret. Refer to usages & examples \nto understand how to use this library. \n\nThe authorizer library exposes these lambda functions that can be called directly:\n- `authorizer` - _ApiKeysAuthorizerFunction_ - used by a custom (this) authorizer that is attached to your API.\n- `deleter` - _ApiKeysDeleterFunction_ - allows revoking access to your API i.e. deletes api keys.\n- `exists` - _ApiKeysExistsFunction_ - allows you to check whether a given API key exists in the database.\n- `generator` - _ApiKeysGeneratorFunction_ - generates api key and api secret pair and saves in an internal database.\n- `validator` - _ApiKeysValidatorFunction_ - validates given api key and api secret against the ones in the database.\n\n### Remarks\n\n[Biomapas](https://www.biomapas.com/) aims to modernise life-science industry by sharing its IT knowledge with other\ncompanies and the community. This is an open source library intended to be used by anyone. Improvements and pull\nrequests are welcome.\n\n### Related technology\n\n- Python3\n- AWS CDK\n- AWS CloudFormation\n- AWS API Gateway\n- AWS API Gateway Authorizer\n- AWS Lambda\n\n### Assumptions\n\nThis project assumes you are an expert in infrastructure-as-code via AWS CloudFormation and AWS CDK. You must clearly\nunderstand how AWS API Gateway endpoints are protected with Authorizers / Custom Authorizers and how it is managed via\nCloudFormation or CDK.\n\n- Excellent knowledge in IaaC (Infrastructure as a Code) principles.\n- Excellent knowledge in API Gateway, Authorizers.\n- Good experience in AWS CDK and AWS CloudFormation.\n- Good Python skills and basics of OOP.\n\n### Useful sources\n\n- AWS CDK:<br>https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html\n- AWS CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html\n- API Gateway with\n CloudFormation:<br>https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigatewayv2-api.html\n- AWS Custom\n Authorizers:<br>https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html\n\n### Install\n\nBefore installing this library, ensure you have these tools setup:\n\n- Python / Pip\n- AWS CDK\n\nTo install this project from source run:\n\n```\npip install .\n```\n\nOr you can install it from a PyPi repository:\n\n```\npip install b-cfn-custom-api-key-authorizer\n```\n\n### Usage & Examples\n\nFirstly, create an api and stage:\n\n```python\nfrom aws_cdk.aws_apigatewayv2 import CfnApi, CfnStage\n\napi = CfnApi(...)\napi_stage = CfnStage(...)\n```\n\nCreate api key custom authorizer:\n\n```python\nfrom b_cfn_custom_api_key_authorizer.custom_authorizer import ApiKeyCustomAuthorizer\nfrom b_cfn_custom_api_key_authorizer.authorization_type import AuthorizationType\n\nauthorizer = ApiKeyCustomAuthorizer(\n scope=Stack(...),\n resource_name_prefix='MyCool',\n api=api,\n # If you specify this, your API will look for \"ApiKey\" and \"ApiSecret\" headers in your request.\n # authorization_type=AuthorizationType.API_KEY_AND_SECRET_HEADERS\n # If you specify this, your API will treat your request with basic auth in mind (\"Authorization\" header).\n # authorization_type=AuthorizationType.AUTHORIZATION_HEADER\n)\n```\n\nUse that authorizer to protect your routes (endpoints):\n\n```python\nfrom aws_cdk.aws_apigatewayv2 import CfnRoute\n\nroute = CfnRoute(\n scope=Stack(...),\n id='DummyRoute',\n api_id=api.ref,\n route_key='GET /dummy/endpoint',\n authorization_type='CUSTOM',\n target=f'integrations/{integration.ref}',\n authorizer_id=authorizer.ref\n)\n```\n\nOnce your infrastructure is deployed, try calling your api endpoint. You will get \"Unauthorized\" error.\n\n```python\nimport urllib3\n\nresponse = urllib3.PoolManager().request(\n method='GET',\n url='https://your-api-url/dummy/endpoint',\n headers={},\n)\n\n>>> response.status\n>>> 401\n```\n\nCreate `ApiKey` and `ApiSecret` by invoking a dedicated api keys generator lambda function:\n\n```python\n# Your supplied prefix for the infrastrucutre.\nresource_name_prefix = 'MyCool'\n# Created generator lambda function name.\nfunction_name = 'ApiKeysGeneratorFunction'\n# Full function name is a combination of both.\nfunction_name = resource_name_prefix + function_name\n\nresponse = boto3.client('lambda').invoke(\n FunctionName=function_name,\n InvocationType='RequestResponse',\n)\n\nresponse = json.loads(response['Payload'].read())\napi_key = response['ApiKey']\napi_secret = response['ApiSecret']\n```\n\nNow try calling the same api with api keys:\n\n```python\nimport urllib3\n\nresponse = urllib3.PoolManager().request(\n method='GET',\n url='https://your-api-url/dummy/endpoint',\n headers={\n 'ApiKey': api_key,\n 'ApiSecret': api_secret\n },\n)\n\n>>> response.status\n>>> 200\n```\n\n#### Exposed lambda functions\n\nThe authorizer exposes these lambda functions that can be called directly:\n- `authorizer` - ApiKeysAuthorizerFunction\n \n```python\nresponse = boto3.client('lambda').invoke(\n FunctionName=prefix + 'ApiKeysAuthorizerFunction',\n InvocationType='RequestResponse',\n Payload=json.dumps({\n 'ApiKey': '123',\n 'ApiSecret': '123'\n }).encode()\n)\n\nresponse = json.loads(response['Payload'].read())\n\n# This will contain a dictionary of IAM based \n# permission either to \"allow\" or \"deny\" the request.\nprint(response)\n```\n\n- `deleter` - ApiKeysDeleterFunction\n \n```python\n# This does not produce a response.\nboto3.client('lambda').invoke(\n FunctionName=prefix + 'ApiKeysDeleterFunction',\n InvocationType='RequestResponse',\n Payload=json.dumps({\n 'ApiKey': '123',\n }).encode()\n)\n```\n\n- `exists` - ApiKeysExistsFunction\n \n```python\nresponse = boto3.client('lambda').invoke(\n FunctionName=prefix + 'ApiKeysExistsFunction',\n InvocationType='RequestResponse',\n Payload=json.dumps({\n 'ApiKey': '123',\n }).encode()\n)\n\nresponse = json.loads(response['Payload'].read())\n\n# Check whether your ApiKey/Secret exists in the database.\nassert response['Exists'] is True\n```\n\n- `generator` - ApiKeysGeneratorFunction\n \n```python\nresponse = boto3.client('lambda').invoke(\n FunctionName=prefix + 'ApiKeysGeneratorFunction',\n InvocationType='RequestResponse',\n)\n\nresponse = json.loads(response['Payload'].read())\n\napi_key = response['ApiKey']\napi_secret = response['ApiSecret']\n```\n\n- `validator` - ApiKeysValidatorFunction\n\n```python\nresponse = boto3.client('lambda').invoke(\n FunctionName=prefix + 'ApiKeysValidatorFunction',\n InvocationType='RequestResponse',\n Payload=json.dumps({\n 'ApiKey': '123',\n 'ApiSecret': '123',\n }).encode()\n)\n\nresponse = json.loads(response['Payload'].read())\n\n# Check whether your ApiKey/Secret is valid.\nassert response['Valid'] is True\n```\n\n### Testing\n\nThis package has integration tests based on **pytest**. To run tests simply run:\n\n```\n\npytest b_cfn_custom_api_key_authorizer_test/integration/tests\n\n```\n\n### Contribution\n\nFound a bug? Want to add or suggest a new feature? Contributions of any kind are gladly welcome. You may contact us\ndirectly, create a pull-request or an issue in github platform. Lets modernize the world together.\n\n\n# Release history\n\n### 3.0.0\n\n* Upgrade CDK support from v1 to v2.\n* Upgrade GitHub pipelines checkout version from v2 to v3.\n* Set GitHub pipelines node version 18.\n* Set GitHub pipelines python version 3.10.\n\n### 2.3.0\n\n* Update of `authorizer` function. Removing of sensitive information form lambda event implemented. \n\n### 2.2.0\n\n* Remove unnecessary dependencies.\n\n### 2.1.1\n\n* Add more integration tests.\n* Update README documentation.\n\n### 2.1.0\n\n* Add ability to specify what type of authentication strategy to use.\n Support for both `ApiKey` / `ApiSecret` and `Authorization` headers.\n\n### 2.0.1\n\n* Dollar sign excluded from API secret.\n\n### 2.0.0\n\n* Restructured project.\n* All lambda functions are under `functions` directory.\n* Add `deleter` function to revoke api keys.\n* Add `exists` function to check whether given api key exists.\n* Add `validator` function to validate api key and api secret.\n* Increase the length of api key (15) and api secret (30).\n* Move authentication checking logic to a lambda layer.\n* Add more lambda-level logging.\n* Add more integrations tests (total 11 as of now).\n* **Very important security improvement** - api secrets are now hashed, to avoid\n leaks if the database is pawned. This is a standard password-level storage security.\n* Greatly improve documentation.\n\n### 1.1.0\n\n* Create a dedicated lambda function to generate\n api keys. You should not interact with the database directly.\n\n### 1.0.0\n\n* Prod-ready version.\n* Added documentation.\n* Added more tests.\n* Some code improvements.\n\n### 0.1.0\n\n* Initial testing done. Authorizer works.\n* Need more tests and edge case handling before promoting to 1.0.0.\n\n### 0.0.1\n\n* Initial build.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Enables ApiKey functionality (like in ApiGateway V1) for ApiGateway V2.",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/biomapas/B.CfnCustomApiKeyAuthorizer.git"
},
"split_keywords": [
"aws",
"cognito",
"api_key",
"authorizer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4e7078e338d7aa640651a2d6fcf6c0a41edc58c1e065b228097abe967dd21e3",
"md5": "9bffb1341cd5e5f50f36a2616c386a91",
"sha256": "29d562ceba8dbcdd3056394023cf7c9484c938af169d3ca858d2aafed18b2959"
},
"downloads": -1,
"filename": "b_cfn_custom_api_key_authorizer-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9bffb1341cd5e5f50f36a2616c386a91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 37908,
"upload_time": "2023-08-03T13:57:59",
"upload_time_iso_8601": "2023-08-03T13:57:59.171637Z",
"url": "https://files.pythonhosted.org/packages/a4/e7/078e338d7aa640651a2d6fcf6c0a41edc58c1e065b228097abe967dd21e3/b_cfn_custom_api_key_authorizer-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8e0e9c09bfdd83027b60634ebd807acee84d5a8dbe9734fca56d6f04b2ec497b",
"md5": "ab81083feee8b1311c0d61d23fbf7625",
"sha256": "886e856922e9246f1d503faaf7da1a443668d187e8e9c28a98e49812a8f96725"
},
"downloads": -1,
"filename": "b_cfn_custom_api_key_authorizer-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ab81083feee8b1311c0d61d23fbf7625",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24730,
"upload_time": "2023-08-03T13:58:02",
"upload_time_iso_8601": "2023-08-03T13:58:02.655173Z",
"url": "https://files.pythonhosted.org/packages/8e/0e/9c09bfdd83027b60634ebd807acee84d5a8dbe9734fca56d6f04b2ec497b/b_cfn_custom_api_key_authorizer-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-03 13:58:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "biomapas",
"github_project": "B.CfnCustomApiKeyAuthorizer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "b-cfn-custom-api-key-authorizer"
}
JSON
