PingOne

Configuring Amazon API Gateway for PingOne Authorize integration

Configure a request parameter-based Lambda authorizer and integrate it with PingOne Authorize and a backend REST API.

Before you begin

Ensure you have:

About this task

The Amazon API Gateway works with Lambda authorizer to manage access to your API resources. When a client makes a request to the backend API, Amazon API Gateway calls the configured Lambda authorizer to create a sideband request for the runtime authorization service. Lambda authorizer then translates the policy response into an IAM policy document for Amazon API Gateway to use in enforcement. If access is permitted, the gateway executes the backend endpoint; if access is denied, the gateway returns a suitable status code and a reason for the denial to the client.

Amazon API Gateway provides PingOne Authorize with client API request metadata, such as header and method, that you can use in writing policies.

The Lambda authorizer has the following limitations:

  • Amazon API Gateway does not expose the request body to PingOne Authorize. This prevents PingOne Authorize from modifying parts of the client request before Amazon API Gateway sends the request to the backend API. For example, although set-headers and set-query statements will execute successfully, their results are not forwarded to the backend API.

  • Amazon API Gateway does not send any part of the backend API response to PingOne Authorize.

Upload the integration kit in AWS and configure it to integrate with PingOne Authorize.

Steps

  1. Create the Lambda function:

    1. Open the AWS Lambda Service.

    2. Click Create function.

    3. Click Author from scratch.

    4. In the Function name field, enter a name.

    5. In the Runtime list, select Node.js 18.x.

    6. In the Architecture section, click x86_64.

      Screen capture of the Lambda runtime settings configured with Node.js 18.x selected as the Runtime, aws-lambda-authorizer file path entered as the handler, and x86_64 selected as the architecture

    7. Click Create function.

  2. Upload the Amazon API Gateway integration kit .zip archive and configure the environment variables:

    1. On the page for your newly created Lambda function, in the Code source pane, select .zip file in the Upload from list.

    2. In the Upload a .zip file modal, click Upload. Select the integration kit .zip archive.

    3. Click Save.

      After saving, your Lambda code source should appear with these files uploaded:

      Screen capture of the Lambda function code editor with the AWS integration kit .zip archive uploaded.

    4. Scroll down, and in the Runtime settings pane, click Edit.

    5. In the Runtime list, select Node.js 18.x.

    6. In the Handler field, enter aws-lambda-authorizer/src/aws-lambda-authorizer.handler.

    7. Click Save.

    8. Scroll up and click the Configuration tab.

    9. In the left navigation pane, click Environment variables. Click Edit.

    10. Add the following environment variables.

      Environment variable Value

      IS_DEBUG_ENABLED

      true or false depending on whether debugging is required. Generally, in a production environment, this variable is set to false.

      SECRET_HEADER_VALUE

      The Gateway Credential from the PingOne console that you saved earlier.

      SERVICE_URL

      The Service URL from the PingOne console that you saved earlier.
      Screen capture of the

    11. Click Save.

      If you have already configured your backend API in AWS, skip to step 4.

      Transient network or service issues sometimes cause API gateway requests to fail with 5xx errors. To control the number of retries before a failed response is returned to the client, use the maxRetries setting in config.js. The default is 1.

  3. Configure a backend REST API:

    1. Open the AWS API Gateway service.

    2. Click Create API.

    3. In the REST API menu, click Build.

    4. In the API name field, enter a name. Leave the rest of the default selections.

      Screen capture of a sample configuration of a backend REST API to be integrated with Lambda authorizer.

    5. Click Create API.

      Lambda authorizer supports integration with both REST and HTTP APIs. For more information, see Using AWS Lambda with Amazon API Gateway.

  4. Configure Lambda authorizer using the Lambda function:

    1. On the page of your backend API, click Authorizers in the left navigation pane.

    2. Click Create New Authorizer.

    3. In the Name field, enter a name.

    4. For the Type, click Lambda.

    5. In the Lambda Function section, select your region and enter the name of the Lambda function that you created earlier.

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

    7. For Lambda Event Payload, click Request.

    8. For Authorization Caching, clear the Enabled check box.

      Screen capture of a sample configuration for a Lambda authorizer created on the basis of a Lambda function.

    9. Click Create.

      You must repeat this Lambda configuration for each backend API that you want to protect with Lambda authorizer.

  5. Assign an API method to Lambda authorizer and configure the integration point:

    1. On the page of your newly created backend API, click Resources in the left navigation pane.

    2. In the Actions list, select Create Resource.

    3. Enter a name and path for your resource.

    4. Click Create Resource.

    5. In the Actions list, select Create Method.

    6. In the list for your newly created resource path, select a REST API method and click the check mark button.

      Resources in your API define one or more methods, such as GET or POST. 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.

    7. For the Integration type, click HTTP.

    8. In the HTTP method list, select a method corresponding to the method that you selected in step 5e.

    9. In the Endpoint URL field, enter the endpoint to which the client API request is sent.

      Screen capture of a sample configuration for a REST API method that will call Lambda authorizer.

    10. Keep the other default values and click Save.

    11. In the method exeuction graphic, click Method Request.

    12. Click the pencil icon next to Authorization and select your configured Lambda authorizer from the list. Click the check mark.

      Screen capture of an example method request setup

  6. Deploy the API Gateway:

    1. On the page for your API, click Resources in the left navigation pane.

    2. In the Actions list, select Deploy API.

    3. In the Deployment stage list of the Deploy API modal, 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.

      Screen capture of the Deploy API modal with options for creating a new production stage.

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

You can only define API services configured with PingOne SSO to integrate with Lambda authorizer.