Integrating Akamai with WordPress VIP

WordPress VIP includes content delivery and caching. If you already use Akamai for these capabilities, WordPress VIP supports direct integration with it.

After completing the integration steps with Akamai, you can:

• Route all live traffic through Akamai
• Configure origin, headers, and TLS settings between Akamai and WordPress VIP
• Apply appropriate caching and purging strategies
• Minimize downtime and launch risks

You configure integration across three layers: the Akamai platform, the WordPress VIP dashboard and application code, and your public DNS records. After launch, keep your IP address lists current if you restrict origin access to specific proxy ranges.

Akamai configuration requirements

Akamai configuration covers origin and performance settings.

Origin configuration

Origin configuration ensures Akamai correctly forwards requests to WordPress VIP.

• Origin hostname: Set this to your assigned WordPress VIP convenience domain (e.g., convenience-domain.go-vip.net).
• Host Header settings: Set the Host HTTP request header to your live production domain (e.g., wpvip.com for this blog). Akamai handles this by passing the incoming host header value requested by the end-user.
• True Client IP header: Enable the “Send True Client IP Header” option within Akamai’s Property Manager.

Performance settings

Configure Akamai’s performance settings to connect properly with WordPress VIP.

• SureRoute: Disable SureRoute within the Akamai Property Manager configuration. WordPress VIP relies on an Anycast network, which can conflict with SureRoute and produce suboptimal routes.
• Preserve Vary for images (Safari/WebP): Akamai removes Vary response headers by default. Because WordPress VIP serves different image formats depending on the browser (serving WebP to Chrome and JPEG or PNG for Safari), removing this header causes Safari to load cached WebP images and display them as broken. To prevent this, you need to configure Akamai to preserve the Vary header and include the Accept header in the cache key for image responses.

Caching strategy

Akamai should cache aggressively while respecting WordPress VIP headers and logged-in user behavior, keeping dynamic content fresh and keeping private content secure.

Do not cache: admin pages

Prevent private, user-specific dashboard pages from entering the shared edge cache.

• Paths: /wp-admin/*, /wp-login.php, and /wp-cron.php.
• Behavior: No Store.

Cache long: static assets

Serve unchanging asset files directly from the nearest edge server for faster load times.

• Paths: /wp-content/* and /wp-includes/*
• Behavior: Cache
• Recommended TTL: 7-30 days

Note: This list is a starting point. You can add more file extensions to this cache rule depending on your site’s needs.

Cache short: dynamic HTML

Apply temporary caching to requests that don’t match the other rules. This improves performance for anonymous users, during sudden traffic spikes.

• Behavior: Cache
• TTL: 1-5 minutes

Logged-in users

Logged-in users don’t need additional Akamai caching rules: WordPress VIP already sets Cache-Control headers to prevent caching of logged-in sessions.

WordPress VIP platform configuration

Once you configure Akamai, move on to WordPress VIP platform configuration. This includes matching the site address in VIP to the site configured in Akamai, verifying requests between Akamai and WordPress VIP, and limiting origin access.

Application URL alignment

Match the site address between Akamai and WordPress VIP. Set the site address (URL) in your WordPress settings to the exact domain name and path Akamai forwards. For example, if Akamai caches traffic for example.com/blog, set the site address in WordPress VIP to example.com/blog too.

Matching these domains prevents rewrite errors and ensures a stable connection.

Request verification

After you configure the site address, verify incoming Akamai requests. To log visitor activity accurately and protect the platform, Akamai must pass specific incoming headers to WordPress VIP on every origin request:

• X-VIP-Proxy-Verification: <secret>
• True-Client-IP: <end-user IP>

Without these headers, all log entries in VIP only show Akamai IP addresses instead of the actual origin. These headers also allow WordPress VIP DDoS protections to accurately deny unwanted requests.

Follow these steps to configure verification tokens:

1. Generate an alphanumeric secret key that is at least 40 characters long
2. In Akamai Property Manager, add a rule to set X-VIP-Proxy-Verification to the secret key
3. Share this secret with the WordPress VIP Support team using a secure, one-time link (Automattic’s QuickForget.com is one option for this). Never paste secret tokens directly into email messages or support tickets
4. Add the following snippet to your vip-config/vip-config.php file to accept the headers and map user IP addresses correctly. It makes sure that $_SERVER['REMOTE_ADDR'] accurately reflects the real end-user instead of the Akamai proxy IP.

<?php
// vip-config/vip-config.php

$proxy_lib = ABSPATH . '/wp-content/mu-plugins/lib/proxy/ip-forward.php';

if (
    ! empty( $_SERVER['HTTP_TRUE_CLIENT_IP'] )
    && ! empty( $_SERVER['HTTP_X_VIP_PROXY_VERIFICATION'] )
    && file_exists( $proxy_lib )
) {
    require_once $proxy_lib;

    // Validates the verification header and sets the client IP correctly.
    Automattic\VIP\Proxy\fix_remote_address_with_verification_key(
        $_SERVER['HTTP_TRUE_CLIENT_IP'],
        $_SERVER['HTTP_X_VIP_PROXY_VERIFICATION']
    );
}

Validation tip: Review your live HTTP request logs and inspect the http_x_vip_ip field to confirm that the platform maps the visitor IP address correctly.

WordPress VIP also supports an IP allow-list approach. Keep in mind that IP-based features may behave differently behind a proxy.

Restrict origin access

Restricting origin access blocks WordPress VIP from accepting requests that don’t come through your reverse proxy. This requires ongoing maintenance to keep IP address ranges current as Akamai’s network changes.

• IP Allow List (VIP Dashboard IP Restrictions): Gather Akamai’s egress IP blocks or Site Shield stable CIDR ranges. From the VIP Dashboard navigate to Environment > IP Restrictions and add the CIDR ranges to block direct public access. After activation, test the block in the terminal:

curl -I https://example.com/

# Expect 403 (or block) when hitting VIP directly from a non-allowed IP
# Expect 200 when the request is routed via the proxy

Keep the list updated anytime Akamai egress changes. If you enable mTLS in the next section, you can retain the allow list as defense-in-depth.

• Mutual TLS (mTLS) between Akamai and WordPress VIP: requires Akamai to present a client certificate that VIP trusts. This can be configured via a WordPress VIP support request:
  • Open a WordPress VIP support ticket requesting mTLS for your application/environment(s) that includes application and environment names (e.g., app-name/production) and the domain(s) you want to protect with mTLS.
  • Provide the CA by pasting the full PEM (including —–BEGIN CERTIFICATE—– … —–END CERTIFICATE—–). If multiple certificates are present, include them in order as a chain.
  • VIP enables mTLS by installing the CA and enforcing “client cert required” at the edge for the specified environment. Note: all domains in the environment will require mTLS at this stage.
  • Configure Akamai by updating your origin configuration to present a client certificate signed by the provided CA when connecting to VIP.
  • Test the configuration: A request without a client certificate should be blocked (HTTP 403) and expose a diagnostic header like x-block-reason: mtls-verify-client. A request with the valid client certificate should succeed (200).

# Expect 403 when no client cert is presented to VIP
curl -I https://www.example.com/

# Expect 200 when the proxy (or your test client) presents a valid cert+key
curl -I --cert client.crt --key client.key https://www.example.com/

In this configuration, public visitors continue using standard TLS with Akamai. The mTLS is applied to connections between Akamai and WordPress VIP.

Cache purging integration

WordPress VIP automatically purges URLs when you publish or update content. If you need to purge manually, purge WordPress VIP before Akamai. This prevents scenarios where Akamai might re-fetch an outdated version from WordPress VIP.

If you use the wp-akamai WordPress plugin, the default behavior doesn’t respect this purge order. You’ll need to modify it to purge WordPress VIP first, following this pseudocode pattern:

on save_post: capture intended Akamai purge
on shutdown:10 (VIP): VIP purges edge
on shutdown:20: run captured Akamai purge

Domains & TLS

Deploy valid TLS certificates on both the public Akamai edge and the WordPress VIP origin for all mapped domains. WordPress VIP recommends using Let’s Encrypt certificates on the origin side.

To allow Let’s Encrypt automated ACME domain validation to succeed through your proxy, route the /.well-known/acme-challenge/* path directly to WordPress VIP over plain HTTP. Ensure Akamai passes this traffic without redirects or extra parameters so the origin can return a valid HTTP 200 response.

DNS cutover process

After completing the previous steps, you’re ready for DNS cutover: test first, then decide when to go live and update public DNS records.

Testing: Modify your local computer’s hosts file to map your production domain directly to the new Akamai CNAME. Browse the site locally to verify user logins, cookie handling, edge caching, and purge functionality before changing public records.

Go-Live: When you are ready to shift traffic publicly, follow this sequence:

• Lower the Time to Live (TTL) values on your existing DNS records to 300 seconds.
• Replace A records with a CNAME record pointing to the hostname provided by Akamai (e.g., site-name.edgekey.net).

Security best practices

Placing Akamai in front of WordPress VIP creates a layered security model:

• Akamai sits closest to the end-user and is your first line of defense, handling DDoS mitigation and Web Application Firewall (WAF) protection. It blocks malicious attacks before it reaches your hosting infrastructure.
• WordPress VIP Platform serves as your core application layer, with built-in, platform-wide rules to safeguard the core network and maintain stability across all environments.

Launch checklist

Integration success

The WordPress VIP team will help verify traffic streams, confirm header validation, and join your launch call. Reach out to VIP Support when you’re ready to coordinate.