Configuring Amazon API Gateway for PingOne Authorize integration
Deploy the Amazon Web Services (AWS) integration kit as a request parameter-based Lambda authorizer and configure it to integrate with PingOne Authorize and Amazon API Gateway.
When an API client sends a request, Amazon API Gateway invokes the Lambda authorizer to evaluate whether access should be granted. The authorizer calls PingOne Authorize to make an access decision based on your policy configurations.
-
If access is allowed, Amazon API Gateway forwards the API client request to the backend REST API.
-
If access is denied, Amazon API Gateway returns an appropriate HTTP status code and a reason for denial to the API client.
Before you begin
Ensure you have:
-
A comfortable level of knowledge of the following interfaces and technologies (or access to developers as needed):
-
Sufficient permissions to create, edit, and publish Lambda functions and modify API endpoints.
-
The AWS integration kit downloadable
.zip
archive. Download the integration kit from the Ping Identity Integration Directory. -
An understanding of policy limitations.
Steps
-
Create the Lambda function:
-
Open the AWS Lambda console.
-
Click Create function.
-
Click Author from scratch.
-
In the Function name field, enter a name.
-
In the Runtime list, select Node.js 20.x.
-
In the Architecture section, click x86_64.
-
Click Create function.
Result:
A page opens for your new Lambda function.
-
-
Upload the integration kit
.zip
archive and configure the environment variables:-
In the Code source section, select .zip file in the Upload from list.
-
In the Upload a .zip file modal, click Upload. Select the integration kit
.zip
archive. -
Click Save.
The Lambda code source should appear with these files uploaded:
-
Scroll down, and in the Runtime settings section, click Edit.
-
In the Runtime list, select Node.js 20.x.
-
In the Handler field, enter
aws-lambda-authorizer/src/aws-lambda-authorizer.handler
. -
Click Save.
-
Scroll up and click the Configuration tab.
-
In the left-hand navigation, click Environment variables, and then click Edit.
-
Add the following environment variables:
Environment variable Value IS_DEBUG_ENABLED
The value is
true
orfalse
depending on whether debugging is required. Set this value tofalse
in production environments.SECRET_HEADER_VALUE
The gateway credential that you saved earlier in the PingOne console.
SERVICE_URL
The service URL that you saved in Setting up PingOne Authorize for Amazon Web Services integration.
MAX_RETRIES
Controls the number of connection retries that the integration kit performs when a PingOne Authorize request fails because of network errors or HTTP 5xx responses. The default is
1
. -
Click Save.
If you have already configured your backend API in AWS, skip to step 4.
-
-
Configure a backend REST API:
-
Open the AWS API Gateway console.
-
Click Create API.
-
In the REST API menu, click Build.
The AWS integration kit only supports and has only been tested with REST APIs.
-
In the API name field, enter a name. Leave the rest of the default selections.
-
Click Create API.
-
-
Configure Lambda authorizer using the Lambda function:
-
On the page for your backend API, click Authorizers in the left-hand navigation.
-
Click Create Authorizer.
-
In the Name field, enter a name.
-
For the Type, click Lambda.
-
In the Lambda Function section, select your region and enter the name of the Lambda function that you created earlier.
-
Leave the Lambda Invoke Role field blank.
By default, the Amazon API Gateway console sets a resource-based policy that grants the API Gateway permissions to invoke Lambda authorizer.
-
Under Lambda Event Payload, click Request.
-
Disable the Authorization Caching toggle.
-
Next to the Identity source type and Key fields, click Remove.
-
Click Create authorizer.
You must repeat this Lambda configuration for each REST API that you want to protect with Lambda authorizer.
-
-
Assign an API method to Lambda authorizer and configure the integration point:
-
On the page for your newly created backend API, click Resources in the left-hand navigation.
-
Click Create Resource.
-
Enter a name and path for your resource.
-
Click Create Resource.
-
In the Methods section, click Create Method.
-
In the Method type list, select an API method.
Resources in your API define one or more methods, such as
GET
orPOST
. Integrating these methods with Lambda authorizer means that any client API request of this method type is forwarded to the configured Lambda function.You can define each resource and method individually, or use special resource and method types that apply to all incoming requests of a certain form. For example, the
ANY
method applies to all incoming requests. -
For the Integration type, click HTTP.
-
In the HTTP method list, select a method corresponding to the method that you selected in step 5f.
-
In the Endpoint URL field, enter the endpoint to which the client API request is sent.
-
Keep the other default values and click Save.
-
Click the Method Request tab.
-
In the Method request settings section, click Edit.
-
In the Authorization list, select your lambda authorizer.
-
Click Save.
-
-
Deploy the API Gateway:
-
On the page for your API, click Resources in the left-hand navigation.
-
Click Deploy API.
-
In the Stage list, do one of the following:
Choose from:
-
Select an existing stage to deploy to.
-
Select New Stage. Enter a name and optional description for the stage.
-
-
Click Deploy.
-
Next steps
Define API services to represent your APIs so that PingOne Authorize can help your API gateway enforce access control. For more information, see Defining your API in PingOne Authorize.
If you’re using AWS to enforce access control, the API service definition must use PingOne SSO as the directory and token source. |
Troubleshooting
To help track and debug issues related to your REST API, you can configure Amazon CloudWatch logging. Learn more in Set up CloudWatch logging for REST APIs in API Gateway in the Amazon API Gateway documentation.