Amazon API Gateway

Amazon Gateway

The Amazon API Gateway enables developers to create, publish and monitor RESTful and WebSocket APIs to allow real-time communication between two applications (for example, the Platform and your Organization's application).

Prerequisites

To configure an Amazon API Gateway Authorizer, the following requirements include:

• Comfortable level of knowledge of the following interfaces and technologies (and/or access to developers as needed):
  • AWS Management Console
  • Lambdas
  • API Gateway
• Sufficient permissions/roles to create, edit, and publish Lambdas and modify the API endpoints. This lets you assign an Authorization Lambda to an API method.
• A Platform Tenant account (contact our Technical Support team for more information).
• At least one API Resource and Method defined and working on the API Gateway.

Configuration on the Platform Side

Configuration of the Amazon API Gateway Authorizer is performed on both the Platform and on the AWS Management Console.

Configuring the Platform:

1. Obtaining the required information to provide to the AWS Management Console
2. Defining the JWT Attributes for Identity Attributes Mapping
3. Setting the Authorization JWT Identifier
4. Downloading the PlainID Authorization Lambda zip archive

Configuring on AWS

Configuring the AWS Management Console to interface with the Platform involves the following steps:

1. Configuring the AWS Management Console involves the following steps:
2. Creating the PlainID Authorization Lambda
3. Uploading the PlainID Authorization Lambda zip archive
4. Configuring Environmental Variables
5. Deploying the Lambda

Setting up the Amazon API Gateway Authorizer

The following information is needed from the Platform in order to configure the Amazon API Gateway Authorizer:

• JsonPath: Identity Workspace Settings > Identity Attributes. Select the relevant Attribute and get the Json Path Value.
• Mapping Value: Environment Settings > Identity Provider (IDP). Select an IDP and get the Mapping Value.
• Client ID: Environment Settings > Authorization Keys and get Client ID
• Secret Key: Environment Settings > Authorization Keys - and add a new Secret Key
• Authorizer ID: Environment Settings > Authorizers - select an existing authorizer or create a new authorizer - and use the Authorizer ID (Available only for saved/existing authorizers).
• URL of PDP (Runtime): Assuming the tenant/account URL is: https://acme-financing.us1.plainid.io, the PDP_URL should be set to:
  https://acme-financing.us1.plainid.io/runtime

Defining the JWT Attributes for Identity Attributes Mapping

The next step is to define the JWT Attributes that you wish to map as Identity Attributes in the Platform. The Identity Attributes can be retrieved from the JWT.

To define the JWT Attributes for Identity Attributes Mapping:

1. Go to the Identity Workspace Settings.
2. Select one of the Identity Attributes.
3. In the JSON Path type the JWT attribute/key name from which the value of the Attribute will be extracted (as seen below).

Setting up the Authorization JWT Identifier

To set the Authorization JWT Identifier:

1. On the Environment Settings screen, click Identity Provider (IDP). The Identity Provide (IDP) screen opens.
2. Click on the relevant Identity Provider. The Identity Provider Details screen opens for the IDP.
3. Click Edit. Fields in the screen that can be edited, become editable.
4. In the Settings for Authorizers section, enter the Mapping Value for the Authorizer. This is a string/text of your choice that must then be included in the JWT payload as the Authorization Attribute. For example: "iss": "https://issuer.acme-bank.com"

Details

Reference

1. This is a required Attribute.
2. This Attribute is dependent on the Identity and Policy definitions - will be different per implementation.

Downloading the PlainID Authorization Lambda zip Archive

When an API Authorizer is created in the Platform, a deployment package is created as well. You can download this zip archive to help you configure the Amazon API Gateway Authorizer.

To download the Authorization Lambda zip archive:

1. From the Environment Settings screen, click API Authorizers. The API Authorizers screen opens.
2. Click on the Amazon API Data Authorizer (or create a new one).
3. In the General Details section, click Download.

Configuring the AWS Management Console involves the following steps:

• Creating the PlainID Authorization Lambda
• Uploading the PlainID Authorization Lambda zip archive
• Configuring Environmental Variables
• Deploying the Lambda

Creating the PlainID Authorization Lambda

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

Uploading the PlainID Authorization Lambda Zip Archive

To upload the PlainID Authorization Lambda zip archive:

1. On the screen of the function you created, from the Upload from field, select .zip file.
2. Select the Lambda zip archive that you downloaded from the Platform (see Configuring the Authorization Platform for the Amazon API Gateway).

Configuring Environmental Variables

To configure relevant Environmental Variables:

1. On the Configuration tab, select Environmental variables. The Environment variables page opens.
   

2. Click Edit and add the following environment variables:

3. Click Save.

Deploy the Lambda

After saving the environment variables to the Lambda file, click Deploy to deploy the changes you made.

After you deploy the API Gateway Authorizer, you will need to amend the code due to a known limitation. For more information, see Known Limitations.

Create a new API Gateway Authorizer

1. Go to the API Gateway Service.
2. Select Authorizers from the menu. The Authorizers screen opens.

3. Click Create New Authorizer, and fill in the relevant information:

Example:

• Click Create, then Grant & Create

Assign the Authorizer to an API Method

• Click to the Method Request link:

• Click on the Edit (pencil) of the Authorization method:

• Choose the custom Authorizer we created earlier (If you don't see it, wait for a few seconds - up to about a minute):

• Click Update (Check Icon):

• Select created method and click Actions > Deploy API:

• You will see a popup which offers you to select an existing stage or create a new stage.
• Select either existing stage or create a new stage, and click Deploy.

Known Limitations

• Part of URL Suffix in PDP needs to be added manually
  • When configuring the Amazon API Gateway, part of the URL suffix of the PDP is missing and must be added manually.

To amend the URL suffix:

1. Open the Lamda function.
2. Click on the Code tab. This opens the Code screen.
3. Double click on the config.json entry in the files list in the left panel.
4. Locate the line with the following code: {"version": "1.2.0", "pdpEndpointV5": "/5.0/decisions"}
5. Add /permit-deny such that the code now appears as follows: {"version": "1.2.0", "pdpEndpointV5": "/5.0/decisions/permit-deny"}
6. After you amend the line, save your changes and then click Deploy.

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