PingOne

Configuring Amazon CloudFront for PingOne Authorize integration

Deploy the Amazon Web Services (AWS) integration kit as a Lambda@Edge function and configure it to integrate with PingOne Authorize and Amazon CloudFront.

Request flow

The following diagram and steps represent a typical request flow with CloudFront, a Lambda@Edge function, an API Gateway origin server, and PingOne Authorize:

Flow diagram of the CloudFront with Lambda@Edge request lifecycle, showing a client request reaching the CloudFront distribution, an authorization decision request being made to PingOne Authorize, content retrieval from a backend API Gateway origin, and the CloudFront distribution responding to the client with the requested resources

  1. The API client makes an HTTP request to the CloudFront distribution’s domain.

  2. The request is routed to a CloudFront edge location.

  3. The Lambda@Edge function is invoked at the viewer request stage and processes the API client request.

    As part of this processing, the Lambda@Edge function calls PingOne Authorize for an authorization decision.

    • If authorized, the API client request proceeds to the next step.

    • If unauthorized, CloudFront sends a deny response to the API client, and the request terminates.

  4. CloudFront forwards the request to the origin server.

  5. The origin server processes the request and sends a response.

  6. CloudFront decides whether to cache the response and sends the final response back to the API client.

Before you begin

To set up a CloudFront distribution and a Lambda@Edge function, you’ll need:

Configuring an API Gateway origin

Create and configure an Amazon API Gateway to serve as the origin for CloudFront.

Steps

  1. Create a backend REST API:

    1. Open the AWS API Gateway console.

    2. Click Create API.

    3. In the REST API section, click Build.

    4. In the API name field, enter a unique name for your API.

      Screen capture of the Rest API configuration page with the edge-optimized endpoint type and the IPv4 address type.

    5. In the API endpoint type list, select an endpoint type for your API.

      Learn more about the available endpoint types in API endpoint types for REST APIs in the Amazon API Gateway documentation.

    6. Click Create API.

      Result:

      A page opens for your new API.

  2. Create an API method:

    1. In the Methods section, click Create method.

    2. In the Method type list, select an API method.

      Screen capture of the Create method page in Amazon API Gateway.

    3. Under Integration type, click HTTP.

    4. Configure the rest of the method to meet your business needs.

    5. Click Create method.

      Result:

      The page for your API opens with the new method defined.

  3. Deploy your REST API:

    1. Click Deploy API.

    2. In the Stage list, select a deployment stage.

    3. (Optional) In the Deployment description field, enter a description.

    4. Click Deploy.

  4. Go to Stages and select the deployed stage.

  5. In the Stage details section, copy the Invoke URL for later use.

Configuring a CloudFront distribution

Create and configure a CloudFront distribution to define the origin servers from which CloudFront retrieves your API resources.

Steps

  1. Open the AWS CloudFront console.

  2. Click Create distribution.

  3. Configure the origin settings:

    1. In the Origin domain field, paste the API invoke URL you copied earlier.

      The Name field is automatically populated with the origin domain name, and the Origin path field is automatically populated with the stage path.

      Screen capture of the CloudFront origin configuration with an API Gateway invoke URL as the origin domain and an API Gateway stage as the origin path.

    2. Under Protocol, click HTTPS only, and leave the default settings.

  4. In the Default cache behavior section, configure caching to meet your business needs.

  5. In the Web Application Firewall (WAF) section, click either Enable security protections or Do not enable security protections.

  6. (Optional) To make it easier to find your CloudFront distribution later, add a Description.

  7. (Optional) To enable CloudWatch logging for your CloudFront distribution, in the Standard logging section, click On, and then configure the settings to meet your business needs.

  8. Click Create distribution.

    It might take a few minutes to deploy the CloudFront distribution. You can check the deployment status in the Details section of the distribution, under Last modified.

Configuring a Lambda@Edge function

Create a Lambda@Edge function and associate it with a CloudFront distribution.

Learn more about Lambda@Edge functions in Customize at the edge with Lambda@Edge in the CloudFront documentation.

Steps

  1. Create a Lambda function:

    1. Open the AWS Lambda console.

      Make sure you’re in the US East (N. Virginia) AWS region. You must be in this region to create Lambda@Edge functions.

    2. Click Create function.

    3. Click Author from scratch.

    4. In the Basic information section, in the Function name field, enter a unique name for the Lambda function.

      Screen capture of the Lambda function’s Basic information page with a runtime of Node.js 20.x, an architecture of x86_64, and a new role created from the Basic Lambda@Edge permissions (for CloudFront trigger) policy template.

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

    6. In the Architecture section, click x86_64.

    7. Click Change default execution role to expand execution role settings.

    8. Under Execution role, click Create a new role from AWS policy templates.

    9. In the Role name field, enter a unique name for the execution role.

    10. In the Policy templates search bar, enter CloudFront to filter the search results, and then select Basic Lambda@Edge permissions (for CloudFront trigger).

      This policy template allows CloudFront to execute the Lambda function when a request matches the configured event trigger.

    11. Click Create function.

      Result:

      A page opens for your new Lambda function.

  2. Update the Lambda function source code:

    1. Click the Code tab.

    2. In the Code source section, in the Upload from list, select .zip file.

    3. In the Upload a .zip file modal, click Upload, and then select the integration kit .zip archive in your local directory.

    4. Click Save.

      Result:

      The Lambda source code should have these files uploaded:

      Screen capture of the Lambda function’s code source with the AWS integration kit .zip archive uploaded.

    5. In the code source file explorer, expand the src folder, and then open the config.js file.

    6. Update the following values:

      • SECRET_HEADER_VALUE: The gateway credential you saved in Setting up PingOne Authorize for Amazon Web Services integration. This value must be a string.

      • SERVICE_URL: The service URL you saved in Setting up PingOne Authorize for Amazon Web Services integration. This value must be a string.

      • IS_DEBUG_ENABLED: The value is true or false depending on whether debugging is needed. This value must be a Boolean, not a string. Set this value to false in production environments.

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

      Lambda@Edge doesn’t support the use of environment variables for setting these values.

    7. Click Deploy.

  3. Update the Lambda function handler:

    1. Scroll down to the Runtime settings section and click Edit.

    2. In the Handler field, replace the existing value with aws-lambda-authorizer/src/aws-lambda-authorizer.handler.

      Screen capture of the Lambda function’s Runtime settings with Node.js 20.x as the runtime, the AWS integration kit handler, and x86_64 as the architecture.

    3. Click Save.

  4. Deploy the Lambda function to Lambda@Edge:

    1. In the Actions list, select Deploy to Lambda@Edge.

    2. Click Configure new CloudFront trigger.

      Screen capture of the Deploy to Lambda@Edge modal with a new CloudFront trigger configured for viewer request events.

    3. In the Distribution list, select your CloudFront distribution.

      If you added a description to your CloudFront distribution, you can enter this description to filter the search results.

    4. In the Cache behavior list, select a cache behavior.

    5. In the CloudFront event list, select Viewer request.

    6. Select the Confirm deploy to Lambda@Edge checkbox.

  5. Click Deploy.

    Result:

    Your Lambda@Edge function will now trigger with each viewer request made to the CloudFront distribution.

Next steps

Define API services to represent your APIs so that PingOne Authorize can help CloudFront enforce access control. Learn more in Defining your API in PingOne Authorize

If you’re using CloudFront and Lambda@Edge to enforce access control, the API service definition must use PingOne SSO as the directory and token source.

Troubleshooting

To track and debug issues related to your Lambda@Edge function and CloudFront distribution, you can configure Amazon CloudWatch logging. Learn more in Logging and monitoring in the CloudFront documentation.