Amazon CloudFront's Origin mTLS Now Supports WebSocket and gRPC, So I Tried It with an ALB Origin

Amazon CloudFront's Origin mTLS Now Supports WebSocket and gRPC, So I Tried It with an ALB Origin

I tested whether CloudFront Origin mTLS works with an ALB origin for WebSocket and gRPC too. With a single client certificate, HTTP, WebSocket, and gRPC all passed the ALB's mTLS (verify) check.
2026.11.19

This page has been translated by machine translation. View original

Introduction

On 2026-11-18, Amazon CloudFront Origin mTLS added support for WebSocket and gRPC traffic.

https://aws.amazon.com/about-aws/whats-new/2026/11/amazon-cloudfront-origin-mtls-websockets-grpc/

Origin mTLS is a feature in which CloudFront presents a client certificate to the origin, and the origin verifies it. In this article, I used an ALB as the origin and tested whether HTTP, WebSocket, and gRPC (unary and bidirectional streaming) can all pass through with a single client certificate.

Architecture and Configuration

Overall Architecture

Requests pass through the client, CloudFront, the ALB (HTTPS, mTLS verify), and EC2, in that order. The ALB has two target groups: one for HTTP and WebSocket (ProtocolVersion is HTTP1) and one for gRPC (ProtocolVersion is GRPC). Requests for the path /echo.Echo/* were routed to the gRPC side.

Client Certificate

I created my own CA with openssl and issued an ECDSA P-256 client certificate with TLS Client Authentication in its EKU. The EKU is specified in the following configuration file, saved as client-ext.cnf.

basicConstraints = CA:FALSE
keyUsage = digitalSignature
extendedKeyUsage = clientAuth

The following commands create ca.key, ca.pem, client.key, and client.pem, and import the client certificate into ACM in us-east-1.

openssl ecparam -name prime256v1 -genkey -noout -out ca.key
openssl req -x509 -new -key ca.key -sha256 -days 30 -subj '/CN=cf-origin-mtls-test-ca' \
  -addext 'basicConstraints=critical,CA:TRUE' -addext 'keyUsage=critical,keyCertSign,cRLSign' -out ca.pem

openssl ecparam -name prime256v1 -genkey -noout -out client.key
openssl req -new -key client.key -subj '/CN=cloudfront-origin-client' -out client.csr
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial -days 30 -sha256 \
  -extfile client-ext.cnf -out client.pem

aws acm import-certificate --region us-east-1 \
  --certificate fileb://client.pem --private-key fileb://client.key --certificate-chain fileb://ca.pem

The ID at the end of the certificate ARN obtained from the import goes into ${CLIENT_CERT_ID} in the distribution configuration described later.

ALB mTLS

I placed the CA certificate in S3 to create a trust store, and added --mutual-authentication Mode=verify to the HTTPS listener. For the listener, I used an ACM public certificate matching the hostname origin.example.com (the origin's server certificate must be issued by a publicly trusted CA).

aws s3api put-object --bucket "$BUCKET" --key ca-bundle.pem --body ca.pem
aws elbv2 create-trust-store --name mtls-verify-ts \
  --ca-certificates-bundle-s3-bucket "$BUCKET" --ca-certificates-bundle-s3-key ca-bundle.pem

aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" --protocol HTTPS --port 443 \
  --certificates CertificateArn="$SERVER_CERT_ARN" --ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \
  --mutual-authentication Mode=verify,TrustStoreArn="$TRUST_STORE_ARN" \
  --default-actions Type=forward,TargetGroupArn="$TG_HTTP"
aws elbv2 create-rule --listener-arn "$LISTENER_ARN" --priority 10 \
  --conditions Field=path-pattern,Values='/echo.Echo/*' --actions Type=forward,TargetGroupArn="$TG_GRPC"

Distribution

The main distribution settings are as follows.

  • Origin: DomainName is the hostname assigned to the ALB, OriginProtocolPolicy is https-only, and OriginSslProtocols is TLSv1.2
  • Origin mTLS: Specify the ARN of the ACM client certificate in OriginMtlsConfig inside CustomOriginConfig
  • HttpVersion: http2
  • Default behavior: Allow 7 methods including POST, the cache policy is Managed-CachingDisabled, and the origin request policy is Managed-AllViewerExceptHostHeader
  • Behavior for /echo.Echo/*: Same settings as the default behavior, with Enabled in GrpcConfig set to true
distribution-config.json

Save the following JSON as distribution-config.json. Replace ${ACCOUNT_ID} and ${CLIENT_CERT_ID} with the values for your environment, and replace origin.example.com in DomainName with the hostname assigned to your ALB.

{
  "CallerReference": "mtls-verify-1119",
  "Comment": "origin mTLS with WebSocket and gRPC",
  "Enabled": true,
  "HttpVersion": "http2",
  "Origins": {
    "Quantity": 1,
    "Items": [
      {
        "Id": "alb-mtls",
        "DomainName": "origin.example.com",
        "CustomOriginConfig": {
          "HTTPPort": 80,
          "HTTPSPort": 443,
          "OriginProtocolPolicy": "https-only",
          "OriginSslProtocols": {
            "Quantity": 1,
            "Items": [
              "TLSv1.2"
            ]
          },
          "OriginReadTimeout": 30,
          "OriginKeepaliveTimeout": 5,
          "OriginMtlsConfig": {
            "ClientCertificateArn": "arn:aws:acm:us-east-1:${ACCOUNT_ID}:certificate/${CLIENT_CERT_ID}"
          }
        }
      }
    ]
  },
  "DefaultCacheBehavior": {
    "TargetOriginId": "alb-mtls",
    "ViewerProtocolPolicy": "https-only",
    "AllowedMethods": {
      "Quantity": 7,
      "Items": [
        "GET",
        "HEAD",
        "OPTIONS",
        "PUT",
        "POST",
        "PATCH",
        "DELETE"
      ],
      "CachedMethods": {
        "Quantity": 2,
        "Items": [
          "GET",
          "HEAD"
        ]
      }
    },
    "CachePolicyId": "4135ea2d-6df8-44a3-9df3-4b5a84be39ad",
    "OriginRequestPolicyId": "b689b0a8-53d0-40ab-baf2-68738e2966ac"
  },
  "CacheBehaviors": {
    "Quantity": 1,
    "Items": [
      {
        "PathPattern": "/echo.Echo/*",
        "TargetOriginId": "alb-mtls",
        "ViewerProtocolPolicy": "https-only",
        "AllowedMethods": {
          "Quantity": 7,
          "Items": [
            "GET",
            "HEAD",
            "OPTIONS",
            "PUT",
            "POST",
            "PATCH",
            "DELETE"
          ],
          "CachedMethods": {
            "Quantity": 2,
            "Items": [
              "GET",
              "HEAD"
            ]
          }
        },
        "GrpcConfig": {
          "Enabled": true
        },
        "CachePolicyId": "4135ea2d-6df8-44a3-9df3-4b5a84be39ad",
        "OriginRequestPolicyId": "b689b0a8-53d0-40ab-baf2-68738e2966ac"
      }
    ]
  }
}
aws cloudfront create-distribution --distribution-config file://distribution-config.json

Managed-AllViewerExceptHostHeader forwards all viewer headers except Host to the origin, so the Sec-WebSocket-* headers needed for the WebSocket handshake are also forwarded. I did not create a dedicated behavior for WebSocket and passed it through the default behavior.

Since gRPC uses HTTP/2, I set HttpVersion for the whole distribution to http2. Origin mTLS has no dedicated settings for WebSocket or gRPC; I simply added OriginMtlsConfig to the ordinary configuration described so far.

Verification

In the following, $CF_DOMAIN is the distribution's domain name (xxxx.cloudfront.net). None of the clients hold a certificate when connecting to CloudFront. The verification server on EC2 returns in its response the values of the X-Amzn-Mtls-Clientcert-* headers added by the ALB (information about the client certificate verified by the ALB).

WebSocket

I prepared a client that connects via CloudFront using Python's websockets. Save it as client/ws_client.py.

import asyncio
import sys

from websockets.asyncio.client import connect

async def main(url: str) -> None:
    async with connect(url) as ws:
        print("handshake:", ws.response.status_code, ws.response.reason_phrase)
        print("first message:", await ws.recv())
        for text in ("hello", "world"):
            await ws.send(text)
            print("echo:", await ws.recv())

asyncio.run(main(sys.argv[1]))
docker run --rm -v "$PWD/client:/app:ro" -w /app python:3.12-slim \
  sh -c "pip install -q websockets && python ws_client.py wss://$CF_DOMAIN/ws"

With WebSocket, the client certificate information is included in the first message.

handshake: 101 Switching Protocols
first message: {"hello": "origin", "mtls": {"serial-number": "2E41B678…6F675B", "issuer": "CN=cf-origin-mtls-test-ca", "subject": "CN=cloudfront-origin-client"}}
echo: origin-echo: hello
echo: origin-echo: world

gRPC

The proto used for verification is as follows. Save it as origin/echo.proto.

syntax = "proto3";

package echo;

service Echo {
  rpc Unary(Msg) returns (Msg);
  rpc Bidi(stream Msg) returns (stream Msg);
}

message Msg {
  string text = 1;
}

A gRPC request path has the form /package-name.service-name/method-name. In this proto, the package name is echo and the service name is Echo, so the path for the behavior and the ALB rule is /echo.Echo/*.

I called unary with grpcurl. With gRPC, the client certificate information is included in the response header x-origin-mtls-subject. I omitted the lines for headers such as date, via, and x-amz-* from the output.

docker run --rm -i -v "$PWD/origin:/proto:ro" fullstorydev/grpcurl -v \
  -import-path /proto -proto echo.proto -d '{"text":"hello"}' $CF_DOMAIN:443 echo.Echo/Unary
Response headers received:
content-type: application/grpc
server: CloudFront
x-cache: Miss from cloudfront
x-origin-mtls-subject: CN=cloudfront-origin-client

Response contents:
{
  "text": "origin-echo: hello"
}

Response trailers received:
(empty)
Sent 1 request and received 1 response

For bidirectional streaming, I sent three messages from standard input.

printf '{"text":"one"}\n{"text":"two"}\n{"text":"three"}\n' | \
  docker run --rm -i -v "$PWD/origin:/proto:ro" fullstorydev/grpcurl -v \
  -import-path /proto -proto echo.proto -d @ $CF_DOMAIN:443 echo.Echo/Bidi
Response headers received:
content-type: application/grpc
server: CloudFront
x-cache: Miss from cloudfront
x-origin-mtls-subject: CN=cloudfront-origin-client

Response contents:
{
  "text": "origin-echo: one"
}

Response contents:
{
  "text": "origin-echo: two"
}

Response contents:
{
  "text": "origin-echo: three"
}

Response trailers received:
(empty)
Sent 3 requests and received 3 responses

HTTP

HTTP requests sent to the same distribution also passed through without changing any settings. With HTTP, the client certificate information is included in the response body.

curl -sS -i https://$CF_DOMAIN/hello
HTTP/2 200 
content-type: application/json; charset=utf-8
server: Python/3.11 websockets/17.4
x-cache: Miss from cloudfront

{
  "path": "/hello",
  "mtls": {
    "serial-number": "2E41B678…6F675B",
    "issuer": "CN=cf-origin-mtls-test-ca",
    "subject": "CN=cloudfront-origin-client"
  }
}

The Certificate Verified by the ALB

The verification server's log contained records of the WebSocket handshake, the gRPC unary call, and the bidirectional streaming call. The subject, issuer, and serial-number were the same in all of them, and also matched the values in the HTTP response body. CloudFront presents the same client certificate for HTTP, WebSocket, and gRPC alike.

{"kind": "ws-handshake", "mtls": {"serial-number": "2E41B678…6F675B", "issuer": "CN=cf-origin-mtls-test-ca", "subject": "CN=cloudfront-origin-client"}, "extra": ""}
{"kind": "grpc-unary", "mtls": {"serial-number": "2E41B678…6F675B", "issuer": "CN=cf-origin-mtls-test-ca", "subject": "CN=cloudfront-origin-client"}, "extra": ""}
{"kind": "grpc-bidi", "mtls": {"serial-number": "2E41B678…6F675B", "issuer": "CN=cf-origin-mtls-test-ca", "subject": "CN=cloudfront-origin-client"}, "extra": ""}

Connecting Directly to the ALB

These are the results of connecting directly to the ALB (verify mode) without going through CloudFront and without a client certificate. For WebSocket and gRPC (unary only), I ran the same commands used via CloudFront, with the destination changed to the ALB hostname (origin.example.com). The HTTP command is as follows.

curl -sS -v https://origin.example.com/hello

The -v output of curl showed that the TLS handshake succeeded up to the verification of the server certificate. No HTTP status was returned to any client, and the results were as follows.

Client Result
curl (HTTP) The connection was reset when sending the request (curl: (16) Send failure, exit 16)
Python websockets (WebSocket) The handshake was not established (InvalidMessage: did not receive a valid HTTP response)
grpcurl (gRPC unary) The connection could not be established and timed out (Failed to dial target host "origin.example.com:443": context deadline exceeded)

When I sent a request directly to the ALB with the client certificate attached, the response body was returned.

curl -sS --cert client.pem --key client.key https://origin.example.com/hello

Summary

By simply adding OriginMtlsConfig to the ordinary configuration, I confirmed that for WebSocket and gRPC as well, CloudFront presents the same client certificate as with HTTP and passes the ALB's mTLS (verify).

The CloudFront Developer Guide lists the following as features that cannot be used together with Origin mTLS: embedded POPs, VPC origins, and Lambda@Edge origin request / origin response triggers.

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/origin-enable-mtls-distributions.html

To protect origins within AWS, you can use OAC, VPC origins, and so on, but if you want to strengthen authentication between CloudFront and an origin outside AWS, try the newly supported Origin mTLS.

Share this article

AWSのお困り事はクラスメソッドへ