Skip to main content

Enables ApiKey functionality (like in ApiGateway V1) for ApiGateway V2.

Project description

B.CfnCustomApiKeyAuthorizer

Pipeline

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 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

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:

from aws_cdk.aws_apigatewayv2 import CfnApi, CfnStage

api = CfnApi(...)
api_stage = CfnStage(...)

Create api key custom authorizer:

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):

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.

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:

# 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:

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
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
# This does not produce a response.
boto3.client('lambda').invoke(
    FunctionName=prefix + 'ApiKeysDeleterFunction',
    InvocationType='RequestResponse',
    Payload=json.dumps({
        'ApiKey': '123',
    }).encode()
)
  • exists - ApiKeysExistsFunction
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
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
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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

b_cfn_custom_api_key_authorizer-3.0.0.tar.gz (24.7 kB view details)

Uploaded Source

Built Distribution

File details

Details for the file b_cfn_custom_api_key_authorizer-3.0.0.tar.gz.

File metadata

File hashes

Hashes for b_cfn_custom_api_key_authorizer-3.0.0.tar.gz
Algorithm Hash digest
SHA256 886e856922e9246f1d503faaf7da1a443668d187e8e9c28a98e49812a8f96725
MD5 ab81083feee8b1311c0d61d23fbf7625
BLAKE2b-256 8e0e9c09bfdd83027b60634ebd807acee84d5a8dbe9734fca56d6f04b2ec497b

See more details on using hashes here.

File details

Details for the file b_cfn_custom_api_key_authorizer-3.0.0-py3-none-any.whl.

File metadata

File hashes

Hashes for b_cfn_custom_api_key_authorizer-3.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 29d562ceba8dbcdd3056394023cf7c9484c938af169d3ca858d2aafed18b2959
MD5 9bffb1341cd5e5f50f36a2616c386a91
BLAKE2b-256 a4e7078e338d7aa640651a2d6fcf6c0a41edc58c1e065b228097abe967dd21e3

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page