---
title: "CDN Embedder with Google Cloud Service Extensions"
description: "This guide explains how to configure and deploy the Doverunner CDN Embedder using Google Cloud Service Extensions and Cloud CDN."
---
> For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt).

The CDN Embedder leverages Google Cloud Service Extensions to deliver forensically watermarked content through Cloud CDN. 
This guide walks you through configuring and deploying the embedder for your Doverunner Forensic Watermarking implementation.

Sample code is available on GitHub.
[Google Cloud Embedder sample](https://github.com/doverunner/fwm-cdn-embedder-gcp-service-extensions)

The embedder is a Proxy-Wasm plugin written in Go. It is attached to a global external Application Load Balancer as an edge extension, and runs before the Cloud CDN cache lookup. It does not store or serve content: Cloud CDN fetches the rewritten path from your origin.

:::caution[Use AES tokens]
This guide covers AES watermark tokens only. Request session URLs with `wmt_type: aes` (the default). JWT tokens (`wmt_type: jwt`) are not recommended with this embedder: verifying their RS256 signature can exceed the [execution time limit](https://docs.cloud.google.com/service-extensions/docs/quotas) of a Service Extensions plugin (1 ms per request), and a plugin that exceeds the limit is terminated with a `500` response.
:::

```mermaid
sequenceDiagram
    box End User
    participant A as End user
    end
    box Content Service
    participant W as Service site
    end
    box Doverunner
    participant S as Doverunner Session Manager
    end
    box Content Service
    participant B as Load balancer (edge extension)
    participant C as Cloud CDN
    participant D as Origin
    end
    A ->> W: Request playback
    W ->> S: Session URL API request (content path, session data)
    S ->> W: Session URL with the watermark token
    W ->> A: Send Session URL
    A ->> B: Start playback of Session URL (request segments)
    Note right of B: Doverunner CDN-Embedder
    B -->> B: Validate the token and rewrite the path to the 0/1 segment
    alt Token rejected
        B ->> A: 403
    else Token valid
        B ->> C: Request the rewritten path
        opt Cache miss
            C ->> D: Fetch the segment
            D ->> C: Return the segment
        end
        C ->> A: Send mixed segments
    end
    Note right of A: Playback of mixed content
```

The CDN Embedder is responsible for:
- Validating watermark tokens issued by the **Session Manager**  
- Resolving the correct **watermark file path** (based on user/session/variant)  
- Rewriting the request path so that Cloud CDN serves the resolved file, and answering `403` when the token is rejected  

Configuration is primarily done through:
- `config.json` – Watermark token and folder structure configuration, passed to the plugin as its plugin configuration  
- `edge-extension.yaml` – Edge extension that attaches the plugin to the load balancer  

## Configuration

#### Plugin Configuration (`config.json`)

The plugin reads its settings from the plugin configuration you pass when you create the plugin version. Nothing is compiled into the module, so one build serves every deployment. Update `config.json` with the appropriate settings for your deployment:

```json
{
  "aesKey": "YOUR_DOVERUNER_SITE_KEY",
  "type": "unlabeled_a_variant",
  "availableInterval": 60,
  "prefixFolder": ["wm-contents"],
  "wmtPublicKey": "YOUR_PUBLIC_KEY",
  "wmtPassword": "YOUR_PASSWORD"
}
```

`wmtPublicKey` and `wmtPassword` are used only for JWT tokens, which this guide does not cover. Leave them as they are.

:::caution
`config.json` holds secrets: the site key lets anyone issue valid watermark tokens. Do not commit your filled-in copy to a repository. Each plugin version stores its configuration, so limit who can read the plugin in your project.
:::

#### Configuration Parameters

| Parameter | Description |
|-----------|-------------|
| `aesKey` | The Site Key issued by Doverunner ContentSecurity Service |
| `type` | Folder structure of the watermarked files: `unlabeled_a_variant` or `directory_prefix`. See [Watermark File Folder Structure](#watermark-file-folder-structure) |
| `availableInterval` | Token validity period in minutes (set to `0` for unlimited validity) |
| `prefixFolder` | Array of top-level folders containing watermarked files. Corresponds to `prefix_folder` in the watermark token request specification |
| ~~`wmtPublicKey`~~ | ~~PEM-formatted public key for JWT tokens~~. Not used in this guide |
| ~~`wmtPassword`~~ | ~~Password that decrypts the watermark pattern in JWT tokens~~. Not used in this guide |

## Watermark File Folder Structure

Organize your watermarked content on your origin according to the folder structure specified in the `prefixFolder` configuration parameter. The top-level folders should correspond to the `prefix_folder` values defined in your watermark token request specification.

Set `type` to match how the A/B versions are stored on the origin:

- `unlabeled_a_variant`: A/B version segments are stored together in one folder, and B version files have a `b.` prefix.
- `directory_prefix`: A/B versions are stored in separate `0` and `1` folders. Content preprocessed with the T&P service uses this structure.

## How the Embedder Handles Requests

The plugin handles the request headers of every request that matches the edge extension's match condition:

1. If the first path segment is one of the `prefixFolder` entries, the plugin decrypts the token and rewrites the path to the variant file to serve.
2. Any other path passes through unchanged.

Edge extensions run before the URL map and before the Cloud CDN cache lookup, so the path the plugin writes is what Cloud CDN looks up and fetches from the origin. Because the rewritten path carries no token, viewers who receive the same variant of the same segment share one cache entry. The token is still validated on every request, so an expired token is refused even when the segment is cached.

A rejected request gets a `403` from the plugin and never reaches Cloud CDN or the origin. The response body is a short reason, for example `Invalid watermark token`.

:::caution
The match condition decides what is protected: a request that it does not cover is passed to Cloud CDN without the plugin and served as is. Do not let viewers reach the origin directly, without the load balancer: such requests bypass the plugin too.
:::

## Deployment

### Prerequisites

Before proceeding with deployment, ensure you have:

- A Google Cloud project with the Network Services and Artifact Registry APIs enabled
- A global external Application Load Balancer (load balancing scheme `EXTERNAL_MANAGED`). The classic Application Load Balancer does not support extensions.
- An origin that stores the watermarked content, attached to the load balancer as a backend bucket or a backend service with Cloud CDN enabled. See [Set up Cloud CDN](https://docs.cloud.google.com/cdn/docs/using-cdn).
- An Artifact Registry Docker repository in the multi-region `us` location. A plugin used with a global load balancer must be stored in this location. If the repository is in another project, grant the Service Extensions service agent access to it as described in [Create a plugin](https://docs.cloud.google.com/service-extensions/docs/create-plugin).
- The gcloud CLI and Docker
- To build the plugin: Go 1.24 or later and binaryen (`wasm-opt`). You do not need them if you deploy the prebuilt plugin from the GitHub release.

Enable the APIs:

```bash
gcloud services enable networkservices.googleapis.com artifactregistry.googleapis.com
```

### Step 1: Build or Download the Plugin

Build the plugin in the sample directory:

```bash
./packaging/build.sh
```

The script compiles the module with `GOOS=wasip1 GOARCH=wasm` and `-buildmode=c-shared`, optimizes it with `wasm-opt`, and writes it to `dist/plugin.wasm`. It fails if the module and `config.json` together exceed the 5 MiB plugin size limit.

Each [GitHub release](https://github.com/doverunner/fwm-cdn-embedder-gcp-service-extensions/releases/latest) also attaches `doverunner_fwm_embedder_gcp.<version>.zip`, which holds a prebuilt `plugin.wasm` with `config.json`, `Dockerfile` and `LICENSE`. If you use it, run Steps 2 and 3 in the unzipped folder.

### Step 2: Push the Plugin to Artifact Registry

`packaging/Dockerfile` packages the module as a container image (`FROM scratch`, `COPY plugin.wasm plugin.wasm`). If the repository does not exist yet, create it first:

```bash
gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=us
```

Build the image and push it:

```bash
gcloud auth configure-docker us-docker.pkg.dev
docker build --no-cache --platform wasm -f packaging/Dockerfile -t fwm-embedder dist/
docker tag fwm-embedder us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0
docker push us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0
```

In the unzipped release folder, build the image with `docker build --no-cache --platform wasm -t fwm-embedder .` instead.

### Step 3: Create the Plugin

Create the plugin with your `config.json` as the plugin configuration:

```bash
gcloud service-extensions wasm-plugins create fwm-embedder \
    --location=global \
    --image=us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0 \
    --main-version=v3-0-0 \
    --plugin-config-file=config.json \
    --log-config=enable=true,sample-rate=1,min-log-level=INFO
```

### Step 4: Attach the Plugin as an Edge Extension

Save the following as `edge-extension.yaml`:

```yaml
name: fwm-embedder
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules/HTTPS_FORWARDING_RULE
- https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules/HTTP_FORWARDING_RULE
loadBalancingScheme: EXTERNAL_MANAGED
extensionChains:
- name: watermark
  matchCondition:
    celExpression: 'request.path.startsWith("/wm-contents/")'
  extensions:
  - name: fwm-embedder
    service: projects/PROJECT_ID/locations/global/wasmPlugins/fwm-embedder
    failOpen: false
    supportedEvents:
    - REQUEST_HEADERS
```

- `celExpression`: Write one `request.path.startsWith("/<folder>/")` term for **each** `prefixFolder` entry in `config.json`, joined with `||`. The expression can be up to 500 characters long.
- `forwardingRules`: List every forwarding rule whose URL map reaches the origin of the watermarked content: usually the HTTPS rule, and also the HTTP rule unless it only redirects to HTTPS. A request on a forwarding rule that is not listed skips the plugin. A forwarding rule can have only one edge extension. To print the reference of a forwarding rule, run `gcloud compute forwarding-rules describe FORWARDING_RULE --global --format='value(selfLink)'`.
- `failOpen`: With `false` (the default), the load balancer returns an error when the plugin fails, instead of continuing without the plugin.

Import the edge extension:

```bash
gcloud service-extensions lb-edge-extensions import fwm-embedder \
    --source=edge-extension.yaml \
    --location=global
```

The plugin takes a few minutes to reach every location. Then request a session URL from the [Session URL API](https://docs.doverunner.com/content-security/forensic-watermarking/embedding/session-manager/#session-url-api) with `domain` set to the domain of your load balancer and `prefix_folder` set to one of the `prefixFolder` entries, play it through the load balancer, and check that a second request for the same variant is served from the cache: the response has an `Age` header, and the load balancer request log (`resource.type="http_load_balancer"`) shows `httpRequest.cacheHit: true`.

### Update or Roll Back the Plugin

To deploy a new build or a changed `config.json`, create a new plugin version. Pass `--image`, a new `--main-version` and the configuration. You can pass the same image tag when only the configuration changes. `--plugin-config-file` can be used only together with `--image`:

```bash
gcloud service-extensions wasm-plugins update fwm-embedder \
    --location=global \
    --image=us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0 \
    --main-version=v3-0-0-r2 \
    --plugin-config-file=config.json
```

To roll back, set an existing version as the main version without `--image`:

```bash
gcloud service-extensions wasm-plugins update fwm-embedder \
    --location=global \
    --main-version=v3-0-0
```

A plugin can have up to 100 versions. To delete an old version, run `gcloud service-extensions wasm-plugin-versions delete VERSION --wasm-plugin=fwm-embedder --location=global`.

## Troubleshooting

| Response | Cause | Action |
|:---|:---|:---|
| `403` `Invalid watermark token` | The token could not be decrypted. The usual cause is an `aesKey` that is not the Site Key of the site that issued the token. | Check `aesKey` and create a new plugin version. |
| `403` `The watermark token usage period has expired` | The token was issued more than `availableInterval` minutes ago. | Request a new session URL, or adjust `availableInterval`. |
| `403` `Unsafe file path request detected.` | A session URL named a variant file (for example a `b.` file) directly. | This is expected. Play the content through the paths in the session URL's manifest. |
| Segment requests fail, and the rewritten path in the plugin log does not exist on the origin | The usual cause is a `type` value that does not match the folder structure. | Check the folder structure, set `type` again, and create a new plugin version. |
| Session URL requests fail, and the plugin log has no entry for them | The request did not reach the plugin: the path is not covered by `celExpression`, or the forwarding rule is not listed in `forwardingRules`. | Add the missing `prefixFolder` term or forwarding rule, and import the edge extension again. |

## Additional Resources

- [Service Extensions plugins overview](https://docs.cloud.google.com/service-extensions/docs/plugins-overview)
- [Prepare plugin code](https://docs.cloud.google.com/service-extensions/docs/prepare-plugin-code)
- [Create a plugin](https://docs.cloud.google.com/service-extensions/docs/create-plugin)
- [Configure an edge extension](https://docs.cloud.google.com/service-extensions/docs/configure-edge-extensions)
- [Set up Cloud CDN](https://docs.cloud.google.com/cdn/docs/using-cdn)
- [Doverunner Forensic Watermarking Embedding Documentation](https://docs.doverunner.com/content-security/forensic-watermarking/embedding/)

## Support

For additional assistance with CDN Embedder configuration or deployment, please [contact Doverunner support](https://support.doverunner.com/) or consult the comprehensive Forensic Watermarking documentation.