Configuration

Updated
  • Updated on Oct 13, 2025
  • Published on Sep 1, 2024
  • 5 minute(s) read
Prev Next

Authorizing APIs processed by the AWS API Gateway requires setting up an integration between PlainID and the AWS API GW service using PlainID's AWS API Authorizer and the Authorization engine (PAA). The integration setup requires:

  • Setting up an AWS API Authorizer in PlainID Platform.
  • Setting up the Authorizer in your AWS Console, deploy it and associate it with API services in the AWS GW.
  • Modeling of relevant Mappers and Policies in the PlainID Platform to support your API Access use case.

For more information about how to use AWS Lambda, refer to their documentation.

Authorizer Setup in PlainID Platform

The first step of setting up a PlainID AWS API Gateway Authorizer is setting up an Authorizer in the Platform Environment Settings. Refer to Managing Authorizers for more information

Once an Authorizer is defined in the platform you will be able to download the Authorizer's deployment package. The downloaded zip archive, which includes the AWS Authorization Lambda, will help you configure the Amazon API Gateway Authorizer in your AWS console.

Authorizer Setup in AWS Console

Configuring the AWS Management Console to interface with PlainID includes the following steps:

  1. Setting up an Authorization Lambda:
  2. Configuring the API GW to use the Lambda:

Creating the PlainID Authorization Lambda

Creating a Lambda Function

To create a Lambda function:

  1. Open the AWS Lambda Service screen.
  2. Click Create function. The Create function screen is displayed.
  3. Select Author from Scratch
  4. In the Function name field, enter the name of the function (for example: product-demo-authz).
  5. Confirm that the remaining settings are configured as follows:
    • Runtime is set to Node.js
    • Architecture is set to x86_64
  6. Click Create Function.

image.png{height="" width=""}*.

Uploading the PlainID Authorization Lambda Zip Archive

To upload the PlainID Authorization Lambda zip archive:

  1. On the screen of the function you just created make sure you are in the Code tab
  2. Open the Upload from dropdown and select from .zip file.
  3. Select the Lambda zip archive that you downloaded from the Platform and Save.

image.png

image.png

Configuring Environment Variables

The Authorizer set as a Lambda uses Environment Variables to integrate with PlainID and enforce API access:

Variable Key Role/Purpose Sample Value Notes/Instructions
CLIENT_ID Policy Scope identifier used to authenticate PlainID's PDP DTA43IJZSPYKAVZYYV5Q Can be obtained from the PlainID Policy Manager SaaS Tenant/Account: Navigate to Environment Settings > Scopes, and get Client ID and Secret if needed.
AUTH_METHOD Defines if the Authorizer authenticates to the PDP using the Scope secret or a JWT (should be aligned with the Scopes Settings in the Platform) - token
- secret		 Token can be used for PDP Authentication, if the API request already contains a valid supported JWT.

If a token is used in the AUTH_METHOD, a valid JWT will be sent in the Authorization header instead of the CLIENT_SECRET.

If the value is set to secret, then the CLIENT_SECRET is sent to the x-client-secret Header
CLIENT_SECRET Scope secret used for PDP Authentication XXXX
AUTHORIZER_ID APA1D318NDQC1DS Navigate to Environment Settings > Authorizers. then select the Authorizer and copy the Authorizer ID.
If you do not have an Amazon API Gateway Authorizer in the list, refer to Managing Authorizers to learn how to add it.
PDP_URL The PlainID PDP endpoint that is used by the Authorizer to make Authorization requests and get the dynamic policy-based decision. http://{pdp-exposed-host}/api/runtime/ Usually this will be theURL of a PDP deployed as part of customer's PlainID PAA.

This URL should be accessible from customer's AWS Environment over https.
RUNTIME_FINE_TUNE Used to pass additional PDP request parameters and flags as part of the Authorization request made by the Authorizer and sent to the PDP {"includeIdentity": "true"} Refer to our Authorization APIs documentation for more details on potential properties. This parameter should be passed as a JSON string with the relevant PDP properties and values.

Example:
{"entityAttributes": {"region": ["US"]},"combinedMultiValues": true}

To configure the relevant Environment Variables, on the Configuration tab, select Environment variables, click Edit, add/edit the variables and Save.

image.png

Deploy the Lambda

Before completing the Authorization Lambda setup and deploying all changes, you need to make an adjustment to the Authorizer config file:

  • Return to the Code tab
  • Choose the config.jsonfile in the files explorer tree. It will be displayed in the editor similar to this {"version": "1.x.y", "pdpEndpointV5": "/5.0/decisions"}
  • Edit the pdpEndpointV5 by adding the suffix /permit-deny and becomes {"version": "1.x.y", "pdpEndpointV5": "/5.0/decisions/permit-deny"}

Click the Deploy button to complete the setup and apply all changes.

Authorizer Setup in the API Gateway

Add the Authorizer to a configured API Service

To add the Authorizer to a configured API Service in the Gateway (GW):

  1. Go to the API Gateway Service.
  2. Select an API Service configured in the GW.
  3. Select Authorizers from the side menu. The Authorizers screen opens.
  4. Click Create New Authorizer, and fill in the relevant information:
    • Name - Set an Authorizer name
    • Type - Lambda
    • Lambda Function - Choose the Lambda configured in previous step
    • Lambda Invoke Role - leave empty
    • Lambda Event Payload - Select Request
    • Identity Sources - Select Header and set to Authorization
    • Authorization Caching - For testing, uncheck the box, otherwise set your cache duration preference.

image.png

image.png

Assigning the Authorizer to an API Method

To assign the Authorizer to an API Method

    1. Go to the API Gateway Service.
  2. Select an API configured in the GW.
  3. Select Resources from the side menu. The API's Resources screen opens.
  4. Select a specific Method Request link:
    • In the Method request settings section, click on the Edit button
    • Open the Authorization dropdown and choose the custom PlainID Authorizer created in previous steps.
    • Click Save
  5. The custom PlainID Authorizer should be displayed as the value of the Authorization field of the method.
  6. Repeat for each method you want to apply PlainID Authorization on.
  7. To complete the operation, click Deploy API:
    1. A popup appears, asking to select an existing stage or create a new stage.
    2. Select either existing stage or create a new stage, and click Deploy.

image.png

image.png

image.png

Known Limitations

  • Request Body Cannot be Used - The Amazon API Gateway does not expose the API Request Body, so the Request Body cannot be used as part of the Policy calculation (cannot be associated/mapped to an Asset Type Attribute or Action)