The First-Party Serving Path feature lets you recover the unmasked user IP
address by routing a request through your Content Delivery Network (CDN) or web
infrastructure to Google ad servers.

On third-party requests, browser and OS features and network configurations
might mask IP addresses. This masking might impact your ad revenue, geographic
targeting, and invalid traffic (IVT) detection.

Your CDN receives a user's unmasked client IP on all incoming requests to your
domain. This feature provides the following benefits:

- **No client-side code changes**: You don't edit JavaScript or pass parameters manually. Google Publisher Tag (GPT) reads the configured path from your Google Ad Manager settings and runs the recovery request asynchronously.
- **Less overhead**: The request is lightweight, cached locally per page view session, and runs asynchronously along ad slot definitions.
- **Encrypted payload**: By default, this feature returns the user's IP address as an encrypted payload.

This page covers configuring the First-Party Serving Path to your preferred CDN.

## Prerequisites

Before configuring your CDN, do the following:

- Specify a serving path in your Ad Manager account, for example, `/adserver/`. To specify the path, follow the steps in [Method 1: First-party serving path](https://support.google.com/admanager/answer/17133631#first-party&zippy=%2Cmethod-first-party-serving-path-recommended).
  - Make sure that your serving path is unique, and no traffic you send uses this path.
- Have or set the following items:
  - **Target host or origin** : `securepubads.g.doubleclick.net`
  - **Target path** : `/pagead/fpm`
  - **Protocol** : HTTPS with the default port `443`.
  - **Headers** : Set the header as `Host: securepubads.g.doubleclick.net`.
  - **Caching** : Configure your CDN to bypass caching for a route, for example, set the cache policies to bypass cache or the `Cache-Control: no-store` header.
- If your CDN is Cloudflare, you must have a Cloudflare Enterprise tier to create an origin rule.

## Configure your CDN

Configure your CDN or reverse proxy to forward requests matching your configured
path to Google ad servers. Select your preferred CDN:

### Cloudflare

1. [Create a rule in the dashboard](https://developers.cloudflare.com/rules/origin-rules/create-dashboard/) with the following
   values:

   - **Custom filter expression** : Add the following:
     - **Field** : `URI Path`
     - **Operator** : `starts with`
     - **Value** : your path, for example, `/adserver/`.
   - **Host Header Override** : Select **Rewrite to** and add the target host `securepubads.g.doubleclick.net`.
   - **DNS Override** : Select **Override to** and add the target host `securepubads.g.doubleclick.net`.
2. [Create a URL rule rewrite in the dashboard](https://developers.cloudflare.com/rules/transform/url-rewrite/create-dashboard/) with the
   following values:

   - **Custom filter expression** : Add the following:
     - **Field** : `URI Path`
     - **Operator** : `starts with`
     - **Value** : your path, for example, `/adserver/`.
   - **Path** : Select **Rewrite to \> Static \>** and add the `/pagead/fpm` target path.
   - **Query** : Select **Preserve**.

### Amazon CloudFront

1. Follow the steps in [Origin settings](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html) with the
   following values:

   - **Origin domain** : `securepubads.g.doubleclick.net`
   - **Protocol**: HTTPS
2. Follow [Create functions](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/create-function.html) and add the following
   example:

   ```javascript
   function handler(event) {
       var request = event.request;
       request.uri = '/pagead/fpm';
       return request;
   }
   ```

   This example takes the incoming request event, assigns the URI to the
   target path, and returns the request.

   Click **Save changes** , navigate to the **Publish** tab, and click
   **Publish function**.
3. Follow [Update a distribution in the console](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/HowToUpdateDistribution.html#update-distribution-console)
   with the following values:

   - **Path pattern** : your path, for example, `/adserver/*`.
   - **Origin and Origin Groups** : the target host, `securepubads.g.doubleclick.net`.
   - **Cache policy** : Select `CachingDisabled`.
   - **Origin request policy** : Select `AllViewerExceptHostHeader`.
   - **Function associations** :
     - **Viewer request** : Select **CloudFront Function** and add the name of your function.

### Fastly

1. Follow [Adding a host](https://www.fastly.com/documentation/guides/getting-started/hosts/working-with-hosts/#adding-a-host) with the following values:

   - **Address** : the target host, `securepubads.g.doubleclick.net`
   - **Port** : the default port, `443`.
   - **Enable TLS?** : **Yes**
     - **Certificate hostname** : `securepubads.g.doubleclick.net`
       - Select **Match the SNI hostname to the Certificate Name**.
     - **SNI hostname** : `securepubads.g.doubleclick.net`
     - **Override host** : `securepubads.g.doubleclick.net`
2. Follow [Creating VCL snippets](https://www.fastly.com/documentation/guides/full-site-delivery/fastly-vcl/vcl-snippets/using-vcl-snippets/#creating-vcl-snippets) with the following
   example:

       if (req.url ~ "^PATH") {
           set req.backend = F_NAME;
           set req.http.Host = "securepubads.g.doubleclick.net";
           set req.url = regsub(req.url, "^PATH", "/pagead/fpm");
           return(pass);
       }

   Replace the following:
   - `NAME`: the name of the host, for example, `Google_GAM_FPM_Backend`.
   - `PATH`: your path, for example, `/adserver/`.

### Google Cloud

1. Follow [Create the NEG and internet endpoint](https://cloud.google.com/cdn/docs/set-up-external-backend-internet-neg#console) with the
   following values:

   - **Network endpoint group type** : Select **Internet NEG (Global)**
   - **Default port** : `443`
   - **New network endpoint** : Select **Fully qualified domain name
     (FQDN) and port**.
   - **FQDN** : add the target host, `securepubads.g.doubleclick.net`.
2. Create your global backend service and
   [configure custom request headers](https://cloud.google.com/load-balancing/docs/https/custom-headers#working-with-request) with the
   following values:

   - **Backend type** : Select **Internet network endpoint group**.
   - **Protocol** : Select **HTTPS** .
     - **Header name** : `Host`
     - **Header value** : add the target host, `securepubads.g.doubleclick.net`.
3. Follow the steps in [Configure URL maps](https://cloud.google.com/load-balancing/docs/url-map#console).

4. In **Routing rules**, locate your production host rule that matches your
   subdomain.

   Update the path matchers with the `routeRules` configuration:

   ```yaml
   name: NAME
   defaultService: projects/PROJECT_ID/global/backendServices/DEFAULT_BACKEND
   routeRules:
     - priority: 1
       matchRules:
         - prefixMatch: PATH
       service: projects/PROJECT_ID/global/backendServices/BACKEND_NAME
       routeAction:
         urlRewrite:
           pathPrefixRewrite: /pagead/fpm
   ```

   Replace the following:
   - `BACKEND_NAME`: the name of the backend service you created in step 2, for example, `gam-fpm-backend-service`.
   - `DEFAULT_BACKEND`: the default backend service that hosts your website.
     - If you host your website on Cloud Storage, replace `backendServices` with the `backendBuckets` parameter in the resource path of the `defaultService` field.
   - `NAME`: the name of the path matcher, for example, `gam-fpm-matcher`.
   - `PATH`: your path, for example, `/adserver/`.
   - `PROJECT_ID`: your project ID.

## Test your implementation

To verify your CDN proxies the request and passes the IP address, run a
test using the `curl` command:

> [!WARNING]
> **Warning:** Your CDN might block non-browser requests, and your curl request might fail. To troubleshoot this issue, refer to your CDN's documentation.

```bash
curl -i https://example.comPATH
```

Replace `PATH` with your path, for example,
`/adserver/`.

If successful, you receive the following output:

- **HTTP status** : `200 OK`
- **Response content**: A payload from Google backend servers that contains an encrypted IP token by default.

## Troubleshoot your implementation

This section covers workflows to troubleshoot your First-Party Serving Path
implementation in your CDN.

The following table details issues, causes, and solutions to troubleshoot:

| Issue | Cause | Solution |
|---|---|---|
| **You receive the HTTP status 404 or 502 from your CDN** | Path rewrite is not active or the `Host` header is missing. | Verify your rewrite maps to the `/pagead/fpm` target path and `Host` header is overridden to the target host, `securepubads.g.doubleclick.net`. |
| **The IP address isn't updated on ad requests.** | Caching enabled on CDN proxy | Make sure you set the cache policy on the route to the `CachingDisabled` policy or the `Cache-Control: no-store` header. Every client must reach the backend service to evaluate their specific IP address. |
| **SSL or TLS handshake failure** | SNI mismatch on backend origin connection | Make sure you configured your CDN to send the target host `securepubads.g.doubleclick.net` in the TLS SNI extension. |
| **Missing the `ips` parameter in the ad request.** | Ad Manager path doesn't match CDN path | Verify that the path entered in the Ad Manager UI **Global Settings** page matches the path configured on your CDN. For details, see [Pass unmasked publisher-provided IP (Beta)](https://support.google.com/admanager/answer/17133631#zippy=%2Cmethod-first-party-serving-path-recommended). |