aws-cdk-secure-api
An unofficial AWS CDK v2 Construct Library for Secure REST APIs.
- Documentation: https://aws-cdk-secure-api.readthedocs.io.
Install
pip install aws-cdk-secure-api
Constructs
-
SecureRestApi
- A construct to create a (public) REST API secured behind an API key, which needs to be specified in thex-api-key
header for all requests. -
IAMSecureRestApi
- A construct to create a (public) REST API secured behind AWS IAM authentication, which requires IAM credentials to be signed and included in all requests.
Features
- A CDK Construct which sets up a RestApi secured behind (one of):
- API key
- An API key is auto-generated and stored in SSM Parameter Store (which is a free service) as needed.
- Local cache for the API key, so that API calls are not needed in future CDK deployments.
-
AWS IAM authentication
- An IAM User (and Policy/Role) is created with minimal permissions to call / invoke the API.
- The IAM User Credentials (Access Keys) are stored in AWS Secrets Manager.
- API key
- Helper methods for all constructs, such as
add_resource_and_lambda_methods
, to make it easier to integrate a method for an AWS Lambda function for example.
Usage
The SecureRestApi
construct represents a Secure REST API in Amazon API Gateway.
Useadd_resource
,add_lambda_methods
, andadd_methods
to configure the API model, as shown below.
Using a root resource:
from aws_cdk.aws_apigateway import StageOptions
from aws_cdk.aws_lambda import Function, Runtime
from aws_cdk_secure_api import Http, SecureRestApi
# noinspection PyTypeChecker
py_runtime: Runtime = Runtime.PYTHON_3_10
get_handler = Function(self, 'lambda1', runtime=py_runtime, ...)
put_handler = Function(self, 'lambda2', runtime=py_runtime, ...)
api = SecureRestApi(
self, 'api',
rest_api_name='My Secure Service',
# optional: specify a deployment stage
deploy_options=StageOptions(stage_name='dev')
)
api.add_lambda_methods(get_handler, 'GET') # GET /
api.add_lambda_methods(put_handler, Http.PUT, Http.POST) # PUT /, POST /
Using a custom-named resource:
Replace above usage ofadd_lambda_methods
withadd_resource_and_lambda_methods
, as shown below.
# GET /path1
api.add_resource_and_lambda_methods(get_handler, '/path1', 'GET')
# PUT /path2, POST /path2
api.add_resource_and_lambda_methods(put_handler, '/path2', Http.PUT, Http.POST)
The IAMSecureRestApi
construct represents a Secure REST API in Amazon API Gateway,
which requires IAM Authorization.
Using a custom-named resource:
from aws_cdk.aws_apigateway import StageOptions
from aws_cdk.aws_lambda import Function, Runtime
from aws_cdk_secure_api import Http, IAMConfig, IAMSecureRestApi
# noinspection PyTypeChecker
py_runtime: Runtime = Runtime.PYTHON_3_10
get_handler = Function(self, 'lambda1', runtime=py_runtime, ...)
put_handler = Function(self, 'lambda2', runtime=py_runtime, ...)
api = IAMSecureRestApi(
self, 'api',
rest_api_name='My IAM Secure Service',
# optional: specify the name of secret to store IAM User Credentials
config=IAMConfig(secret_name='my-stack/iam-user-access-keys'),
# optional: specify a deployment stage
deploy_options=StageOptions(stage_name='dev')
)
# GET /path1
api.add_resource_and_lambda_methods(get_handler, '/path1', 'GET')
# PUT /path2, POST /path2
api.add_resource_and_lambda_methods(put_handler, '/path2', Http.PUT, Http.POST)
To use an IAM Role instead of attaching a Policy directly to User:
IAMConfig(use_role=True)
AWS Profile
Note that if you normally pass the --profile
to the cdk
tool, for example such as:
cdk deploy --profile my-aws-profile
The CDK construct won't be able to detect the AWS profile in this particular case. A few workarounds can be used for this:
-
The environment variable
AWS_PROFILE
can be set before calling thecdk
tool. -
The
profile
attribute can be passed in to theconfig
parameter forSecureRestApi
. -
The
profile
context variable can be passed in to thecdk
tool, as shown below:cdk deploy --profile my-profile -c profile=my-profile
API Keys
Here is the process that the CDK construct uses for generating or using an API key for a REST API.
- First, it tries to read the API key from local cache, which is located in your
home directory, under
~/.cdk/cache/apigw_api_keys.json
. - If an API key is found, then it proceeds to use the cached key value, and does not perform the following steps.
- An API call is made to read the key from AWS SSM Parameter Store. The param
name is
/{STACK NAME}/api-key
, where{STACK NAME}
is the name of the CDK stack. - If the parameter does not exist, an random API key value is auto-generated, and a new SSM Parameter is created in the same AWS account and region that the CDK stack is deployed to.
- The API key value is then cached on the local drive, under the
~/.cdk/cache
folder.
Stack Outputs
The following stack outputs will additionally be added to the CDK stack:
-
APIEndpoint
- The base endpoint of the Secure REST API.-
Note: this output will not show up if
override_endpoint_name
is disabled in theconfig
parameter.
-
Note: this output will not show up if
-
APIKey
- The API key for the endpoint, which needs to be specified as a value in an HTTP request'sx-api-key
header. -
APIIAMUserCredentials
- The URL link (to input in a browser) for the Secret stored in AWS Secrets Manager containing the AWS IAM Credentials for invoking the REST API. -
APIIAMRoleARN
- The ARN of the IAM Role, used in an AssumeRole API call with the IAM User credentials.
Credits
This package was created with Cookiecutter and the rnag/cookiecutter-pypackage project template.