Using an External Proxy with Alokai

This guide explains how to configure and use an external proxy with the Alokai@Edge feature. Using an external proxy is typically not required, but may be appropriate if you have specific needs—such as supporting a gradual, "page-by-page" migration to Alokai while maintaining your existing proxy solution.

Follow the steps below to restrict access and review important information about certificate management when using an external proxy with Alokai.

Important considerations before using an external proxy

Placing an external proxy or CDN in front of Alokai@Edge changes which host Alokai treats as the client. Requests arrive from the external proxy rather than from the end user's browser, and an additional caching and security layer is introduced above the Alokai edge. The following consequences should be evaluated before adopting this topology.

Edge caching and cache purging

Alokai's CDN caching continues to operate at the Alokai edge. If the external proxy also caches responses, two independent cache layers exist, each with its own TTLs. Cache purges issued from the Alokai Console — including surrogate-key and "purge all" operations — invalidate only the Alokai cache. They do not propagate to the external proxy, which may continue to serve stale content after a purge until its own TTL expires or a separate purge is performed on that layer. Caching behavior must therefore be coordinated across both layers. Features that depend on requests reaching the Alokai edge, such as surrogate-key tagging (which uses the Host header value), apply only to traffic that is not served from the external proxy's cache.

Security features that depend on the client IP

Alokai's edge security features — including the WAF, Bot Protection, IP-based rate limiting, and the IP access list — evaluate the connecting client. When an external proxy is placed in front of Alokai@Edge, the connecting client is the proxy, and requests appear to originate from a limited set of proxy IP addresses. IP allowlists and blocklists, per-client rate limits, and IP-reputation signals lose effectiveness or produce false positives, as individual end users can no longer be distinguished.

Recovering the original client IP requires the external proxy to forward it in a header and requires Alokai to be configured to read and trust that header. This configuration is not enabled by default and cannot be self-served from the Console; it must be arranged by contacting Alokai support. Because client-supplied forwarding headers can be spoofed, the trust relationship is established deliberately as part of that setup.

Bot management effectiveness

Bot detection depends on signals derived from the original client connection, including the client IP and its reputation, TLS characteristics, and per-client behavioral patterns. When traffic is proxied, TLS is terminated at the external proxy, and the connection observed by Alokai originates from the proxy rather than the end user. Fingerprinting and IP-reputation signals are consequently degraded, and bot mitigation at the Alokai edge becomes less effective. Where bot management is a requirement, it is generally most effective at the layer that terminates the end user's connection.

Reduced visibility for debugging and support

Because Alokai observes only the request as forwarded by the external proxy, visibility into the original request is reduced. Access logs reflect the proxy's IP addresses rather than those of end users, geolocation and analytics reflect the proxy's location, and any headers the proxy rewrites, removes, or adds are what Alokai receives. During incident investigation, a specific end user's request cannot be reliably correlated with the request received at the Alokai edge unless the original client attributes are faithfully forwarded. This can extend diagnosis time and make certain issues difficult to reproduce. Forwarding the real client IP and preserving original request headers is recommended wherever possible.

Added latency and loss of edge proximity

Alokai@Edge is served from a global network of points of presence located close to end users. Routing all traffic through an external proxy introduces an additional network hop and an additional TLS termination. If the proxy is hosted in a single region, it can offset the latency benefit of a globally distributed edge. The location of the proxy relative to the user base should be taken into account.

Operational responsibility

This topology distributes configuration and ownership across two systems. Responsibilities such as TLS certificate management, caching rules, and security policy may reside partly on the external proxy and partly within Alokai. This increases the potential for configuration drift and makes it important to document which layer is responsible for each function.

Follow the steps below to restrict access and review important information about certificate management when using an external proxy with Alokai.

Limit access to Alokai instance

To restrict access to your Alokai@Edge instance (via the technical domain), you can use one or both of the following methods: IP allowlist and header allowlist. It is strongly recommended to enable at least one of these options to ensure that only traffic from your proxy provider can reach your Alokai instance.

IP allowlist

Add the IP addresses used by your external proxy provider to the allowlist. Make sure to include all relevant IPs to ensure only traffic from your proxy can access your Alokai@Edge instance. Refer to your proxy provider’s documentation to obtain the complete and up-to-date list of their IP addresses.

For detailed instructions on configuring the IP allow list, see the article Manage IP access list.

Header allowlist

You can further restrict access to your Alokai@Edge instance by requiring a custom HTTP header on incoming requests. Configure your proxy provider to add this header with a unique, hard-to-guess value to every request forwarded to Alokai. Only requests containing the correct header and value will be allowed access.

For more information on configuring an Header allow list, see Manage header access list.

Certificate managed by Alokai

If you are using an external proxy, you should manage the SSL certificate for your custom domain directly on your proxy or load balancer. This approach allows you to provision and install your own certificate, rather than relying on Alokai to handle certificate management for your domain. For secure communication between your proxy and Alokai@Edge, use the technical domain (<instance_name>.i.alokai.cloud) instead of your custom domain.

If you require a custom domain on Alokai@Edge, we strongly recommend managing your own TLS certificate rather than relying on Alokai to handle certificate management. Using a custom TLS certificate gives you full control over security, renewal processes, and compatibility with your infrastructure.

If you cannot use a custom certificate for your domain, we generally recommend using the DNS-01 challenge method for certificate issuance and renewal, as it is more secure and does not require exposing any HTTP endpoints on your external proxy. With DNS-01, you prove domain ownership by creating specific DNS records, allowing you to keep all HTTP traffic fully restricted. This approach is preferred over HTTP-01 challenges, which require unauthenticated HTTP access to certain paths.

If using the DNS-01 challenge is not possible, ensure your external proxy is configured to allow ACME HTTP-01 challenge requests.

Allow ACME Challenge Requests on the External Proxy

When using a certificate managed by Alokai certificate, it is essential to allow ACME HTTP-01 challenge requests through your external proxy or load balancer. These requests are made to paths under /.well-known/acme-challenge/ and are required for automated SSL certificate issuance and renewal.

Make sure your external proxy configuration explicitly permits unauthenticated HTTP access to /.well-known/acme-challenge/ so that the ACME provider can reach your Alokai instance as needed.