Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

403 Forbidden when a WebSocket API goes through CloudFront

ErrorUnexpected response code: 403 during the WebSocket handshake

Short answer

Through CloudFront, a WebSocket handshake needs the right headers forwarded, and API Gateway needs its own host name rather than your CloudFront domain. Attach an origin request policy that forwards the viewer headers except Host (AllViewerExceptHostHeader), and make sure the Sec-WebSocket headers reach the origin.

  • Applies to CloudFront, API Gateway WebSocket API
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Connect to the API Gateway URL directly. If that works and the CloudFront URL gives 403, the problem is in the CloudFront cache behavior. You can use wscat if you have it, or any WebSocket client.

    npx wscat -c wss://abc123.execute-api.us-east-1.amazonaws.com/prod
    npx wscat -c wss://d111111abcdef8.cloudfront.net/prod
  2. 2Match what you see, then jump to its fix

    1. 1403 only through CloudFront; the direct execute-api URL connectsCloudFront forwards its own Host header to API GatewayFix
    2. 2The upgrade request is rejected and the origin never sees Sec-WebSocket-KeyThe WebSocket handshake headers are not forwardedFix

What does the error look like?

  • Unexpected response code: 403 during the WebSocket handshake
  • 403 Forbidden on the upgrade request, while the execute-api URL works directly

Cause 1 of 2

CloudFront forwards its own Host header to API Gateway

1Check

Open the cache behavior and read its origin request policy. If the Host header from the viewer is forwarded (for example with the AllViewer policy), the origin gets your CloudFront domain name where it expects its own.

aws cloudfront get-distribution-config --id E2EXAMPLE --query 'DistributionConfig.DefaultCacheBehavior.OriginRequestPolicyId'

2Fix

Use the managed origin request policy AllViewerExceptHostHeader (ID b689b0a8-53d0-40ab-baf2-68738e2966ac). It is meant for API Gateway origins, and CloudFront then sets the Host header to the origin's domain name.

# in the distribution config, on the cache behavior:
"OriginRequestPolicyId": "b689b0a8-53d0-40ab-baf2-68738e2966ac"

3Verify

Wait for the distribution to finish deploying, then connect through CloudFront again.

npx wscat -c wss://d111111abcdef8.cloudfront.net/prod

Confirmed by docs.aws.amazon.com

Did this fix it?

Cause 2 of 2

The WebSocket handshake headers are not forwarded

1Check

CloudFront needs either all viewer headers forwarded, or at least Sec-WebSocket-Key and Sec-WebSocket-Version named in the origin request policy. A policy that forwards no headers breaks the handshake.

aws cloudfront list-origin-request-policies --type managed --query 'OriginRequestPolicyList.Items[].OriginRequestPolicy.OriginRequestPolicyConfig.Name'

2Fix

If you cannot use AllViewerExceptHostHeader, create a custom origin request policy that forwards the WebSocket headers (Sec-WebSocket-Key, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Accept and Sec-WebSocket-Extensions) and still leaves Host out.

# origin request policy, header names to forward:
Sec-WebSocket-Key
Sec-WebSocket-Version
Sec-WebSocket-Protocol
Sec-WebSocket-Accept
Sec-WebSocket-Extensions

3Verify

Connect through the CloudFront domain after the change deploys.

npx wscat -c wss://d111111abcdef8.cloudfront.net/prod

Confirmed by docs.aws.amazon.com

Did this fix it?

How do I stop it coming back?

  • Test the execute-api URL directly first, so you know which layer is returning the 403.
  • Keep the WebSocket cache behavior separate from your website behaviors.
  • Remember CloudFront supports WebSocket only over HTTP/1.1.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.