Protecting APIs with MicroPerimeter™ Custom Authorizer on AWS API Gateway

Instructions on how to protect your APIs deployed behind the AWS API gateway using MicroPerimeter™ Custom Authorizer

Prerequisites

  • You have an AWS services account.
  • You have some APIs available in the AWS API Gateway service.
  • You have login credentials for the ACP portal.

Select workspace

  1. In your browser, navigate to ACP and log in with your credentials.

  2. In the Workspace Directory view, select a workspace that you want to enter.

Create AWS GW

  1. In the workspace, select APIs from the sidebar.

  2. Select the GATEWAYS tab.

  3. Select ADD GATEWAY.

  4. Select Amazon API Gateway, enter the name and the description for the gateway, and select NEXT.

    Note

    You can add only one AWS API gateway per workspace.

  5. In the Gateway Management view, go to the QUICK START tab and follow the provided instruction to configure your gateway.

    1. Select DOWNLOAD AUTHORIZER to download the Cloudentity MicroPerimeter AWS custom authorizer and install it (see step 4 in Configure AWS Lambda).

    2. Connect your AWS API gateway with ACP.

      Result

      The authorizer funnels information about protected APIs to ACP.

    3. Back in the ACP administrator portal (Gateway Management view > QUICK START tab), select CONNECT TO YOUR APIS to connect APIs and enable enforcement policies.

    Result

    The predefined set of API groups has been imported and displayed in the APIs tab of the Gateway Management view. The API groups are ready to be connected to services.

  6. To access your gateway settings, select the SETTINGS tab.

  7. In the SETTINGS tab, copy values of ACP_CLIENT_ID, ACP_CLIENT_SECRET, and ACP_ISSUER_URL.

    Note

    ACP_CLIENT_ID, ACP_CLIENT_SECRET, and ACP_ISSUER_URL are needed to configure the authorizer in the AWS Lambda portal (step 4 in Create a function).

  8. Select Save.

Configure AWS Lambda

Create a function

  1. Go to AWS Lambda in AWS and select Functions from the left sidebar.

  2. Select Create function. Enter the function name (for example, cloudentity-microperimeter-authorizer) and set the runtime to Go 1.x.

  3. Go to the Function code section and upload the ZIP archive.

  4. Go to the Basic settings section and select Edit.

  5. In the Edit basic settings view, set the handler to cloudentity-mp-aws-gw-authorizer.

  6. Go to the Environment variables section and set the ACP_CLIENT_ID, ACP_CLIENT_SECRET, ACP_ISSUER_URL environment variables to the client ID, client secret, and issuer URL respectively.

    Note

    For ACP_CLIENT_ID, ACP_CLIENT_SECRET, and ACP_ISSUER_URL, paste the values generated for your new gateway in the ACP administrator portal (step 8 in Connect the gateway).

    Optional settings

    You can also modify

    • CONFIG_REFRESH_INTERVAL, which represents the frequency of retrieving policies from ACP by the authorizer and defaults to 5 seconds
    • DISABLE_ANALYTICS, which can be changed from its default value (false) to true to turn off the analytics.

Add a trigger

  1. Select + Add trigger.

  2. In the Add trigger view,

    1. Select EventBridge (CloudWatch Events) from the top select box.

    2. Select Create a new rule from the Rule select box.

    3. Enter a name for the rule into the Rule name field, for example every-minute.

    4. Specify Rule type by selecting Schedule expression.

    5. Enter a schedule expression into the Schedule expression field, for example, rate(1 minute).

    6. Select Add.

Configure Lambda permissions

  1. Make sure that you are on the page of your function in the AWS Lambda console.

  2. Select the Permissions tab and, next, click on the Role name link in the Execution role field.

  3. In the Summary view, select Add inline policy.

  4. In the Create policy view, add permissions for the API Gateway service.

    1. In the Visual editor tab, set Service to API Gateway.

    2. In the Actions section, enable All API Gateway actions.

    3. In the Resources section, select All resources.

  5. In the same Create policy view, add permissions for the Lambda service.

    1. Select Add additional permissions.

      Result

      A visual editor for another policy opens.

    2. Set Service to Lambda.

    3. In the Actions section, enable All Lambda actions.

    4. In the Resources section, go to the Function area and select Add ARN.

    5. In the Add ARN pop-up window, enter a region and a name for your function.

      Alternatively

      • Copy ARN from your Lambda function page.

      • Paste the copied ARN into the Specify ARN for function field.

    6. Select Add.

  6. In the Create policy view, select Review policy.

  7. In the Review policy view, enter the name for your policy and select Create policy.

Result

Your new policy is ready: you have configured permissions for your Lambda function.

Note

The time required for propagating AWS permissions can vary and it may take a while.

Connect a service

There are two ways to connect AWS API groups to ACP services: starting from the gateway to be connected or starting from the service that you want to connect.

From the gateway

  1. From the list of available gateways, select your newly-created AWS gateway and go to its APIs tab.

    Result

    A list of imported API groups opens.

  2. From the list of API groups available, select an API group and, from its drop-down menu, pick a service to which you’d like to connect the API group.

    Note

    You can connect an API group to an existing service or a new one you create, both options available from the same service drop-down menu.

    Result

  3. Get back to AWS Lambda portal and go to your Amazon API gateway. In Resources, select Actions > Deploy API.

  4. In the Deploy API popup window

    1. Select Deployment stage corresponding to the stage that you bound the services to in ACP.

    2. Enter Deployment description.

    3. Select Deploy.

From the service

  1. Select APIs from the left sidebar and go to the AUTHORIZATION tab.

  2. Pick a service that you want to connect and select ADD GATEWAY API for the selected service.

  3. In the Add Gateway API Groups popup window, select an API gateway and an API group to be connected. Click Connect to proceed.

    Result

  4. Get back to AWS Lambda portal and go to your Amazon API gateway. In Resources, select Actions > Deploy API.

  5. In the Deploy API popup window

    1. Select Deployment stage corresponding to the stage that you bound the services to in ACP.

    2. Enter Deployment description.

    3. Select Deploy.

Result

In the APIS tab of the Gateway Management view, you can see specific API groups integrated to services.

Apply a sample policy

  1. Create a policy.

  2. Select APIs from the sidebar and go to the AUTHORIZATION tab.

  3. Select a service protected by the Amazon API gateway and any API with authorization status None.

  4. In the Edit API popup window, select Policy from the dropdown list and click Update to proceed.

Result

You have successfully assigned a policy to your API.

Confirm the enforcement

  1. Go to your Amazon API Gateway dashboard and select the API secured with ACP.

  2. From the left sidebar, go to Stages and select the stage with your API.

  3. Copy the invoke URL of the stage.

  4. Execute the curl command in the terminal of your computer.

curl -v {invoke_url}/pets -H "Authorization: Bearer invalid_token"

Result

The curl call returns the 403 Forbidden status code as the policy does not pass with a invalid token header.

Follow-up

With your AWS API gateway set up, you can configure your Lambda function to retrieve contextual information on users accessing the Lambda function. For more information, see Acquiring contextual information on users accessing your Lambda.