---
title: "CloudFront Embedder 연동 가이드"
description: "본 문서에서는 Amazon CloudFront CDN을 사용하는 서비스 사이트를 위해 CloudFront용 워터마크 임베딩 모듈을 Lambda@Edge로 적용하는 방법에 대하여 설명합니다."
---
> For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt).

본 문서에서는 Amazon CloudFront CDN을 사용하는 서비스 사이트를 위해 CloudFront용 워터마크 임베딩 모듈을 Lambda@Edge로 적용하는 방법에 대하여 설명합니다.

:::caution[리전 요구 사항]
Lambda@Edge 함수는 **반드시 미국 동부(버지니아 북부) `us-east-1` 리전에서 생성해야 합니다** — 이는 Doverunner의 정책이 아니라 Lambda@Edge에 대한 AWS의 필수 요구 사항입니다. 다른 리전에서 함수를 생성하면 CloudFront에 연결할 수 없으며, 함수를 삭제하고 `us-east-1` 리전에서 다시 생성해야 합니다.
:::

```mermaid
sequenceDiagram
    box 최종 사용자
    participant A as 최종 사용자
    end
    box 콘텐츠 서비스
    participant B as CloudFront CDN
    end
    A ->> B: 세션 URL 재생 시작 (세그먼트 요청)
    Note right of B: CloudFront Embedder
    B -->> B: 세션 URL에 따른 0/1 세그먼트 조합
    B ->> A: 조합된 세그먼트 전달
    Note right of A: 조홥된 콘텐츠 재생
```

## AWS CDK를 이용한 CloudFront Embedder 세팅
AWS CloudFront 와 lambda@edge 연동 하는데 필요한 리소스 등을 한번를 생성할 수 있는 CDK 샘플 소스가 제공됩니다.
[**CloudFront Embedder CDK 샘플**](https://github.com/inka-pallycon/fwm-cdn-embedder-generator)


## 직접 CloudFront Embedder 세팅
Lambda@Edge 설정에 필요한 CloudFront Embedder 파일은 [샘플 다운로드 페이지](https://docs.doverunner.com/content-security/forensic-watermarking/getting-started/fwm-downloads/)에서 다운로드 받을 수 있습니다.

:::note 

본 문서에 작성된 내용은 향후 AWS 측의 업데이트에 따라 최신 버전의 AWS 콘솔 UI와 맞지 않게 될 수 있습니다. 실제 AWS 콘솔과 상이한 부분이나 잘못된 가이드 문서 링크가 있는 경우, [헬프데스크](https://support.doverunner.com)를 통해 문의해 주시기 바랍니다.

:::

## 동영상 튜토리얼

CloudFront Embedder를 통한 포렌식 워터마킹 임베딩 방법을 설명하는 영상입니다.

[동영상: YouTube](https://www.youtube.com/watch?v=TyZ2X8tIaHQ)

> **Doverunner Lab에서 따라 하기**: 단계별 레슨 [워터마크 삽입](https://lab.doverunner.com/ko/academy/courses/getting-started-forensic-watermarking/watermark-embedding)

## Lambda@Edge 사용 가이드

Amazon CloudFront CDN에서의 Lambda@Edge 사용에 대해 익숙하지 않은 경우, 다음 단계로 진행하기 전에 아래 AWS 온라인 문서를 참고해 사용법을 숙지해 주실 것을 권장합니다.

 - [Lambda@Edge 함수 생성 및 사용 시작하기](https://docs.aws.amazon.com/ko_kr/AmazonCloudFront/latest/DeveloperGuide/lambda-edge-how-it-works.html)
 - [자습서: 간단한 함수 생성](https://docs.aws.amazon.com/ko_kr/AmazonCloudFront/latest/DeveloperGuide/lambda-edge-how-it-works-tutorial.html)

## IAM 권한 및 역할 생성

Lambda@Edge를 구성하기 위해서는 우선 해당 기능에 필요한 IAM 권한과 실행 역할을 생성해야 합니다. AWS 콘솔의 `IAM` 서비스 화면에서 [해당 가이드](https://docs.aws.amazon.com/ko_kr/AmazonCloudFront/latest/DeveloperGuide/lambda-edge-permissions.html)를 참고해 다음과 같이 권한 및 역할을 생성합니다.

 - `lambda:GetFunction`, `lambda:EnableReplication*`, `iam:CreateServiceLinkedRole`, `cloudfront:UpdateDistribution`, `cloudfront:CreateDistribution` 권한을 추가하여 역할을 생성합니다.

> 권한 추가를 위해서는 우선 대상 서비스(Lambda)를 지정해야 합니다. 또한 `lambda:EnableReplication*` 권한을 추가하려면 우선 `lambda:EnableReplication` 권한 추가 후 JSON 코드를 수정해야 합니다.

> `iam:CreateServiceLinkedRole` 권한의 리소스를 `"Resource": "*"`로 지정하면 정책 편집기에 경고가 표시됩니다. 필요한 경우 리소스 범위를 `arn:aws:iam::*:role/aws-service-role/replicator.lambda.amazonaws.com/*`로 제한할 수 있습니다.

 - Lambda access log를 cloudwatch logs로 수집하기 위해 logs 관련 권한을 추가합니다.
    ```json
    {
        "Effect": "Allow",
        "Action": [
            "logs:CreateLogGroup",
            "logs:CreateLogStream",
            "logs:PutLogEvents"
        ],
        "Resource": "arn:aws:logs:*:*:*"
    }
    ```

 - 생성한 role의 `Trust Relationship` 탭에 아래 역할을 추가합니다.
    ```json
    { 
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": { 
                    "Service": [
                        "lambda.amazonaws.com", 
                        "edgelambda.amazonaws.com" 
                    ] 
                }, 
                "Action": "sts:AssumeRole" 
            } 
        ] 
    }
    ```

## Lambda@Edge 함수 생성

- AWS 콘솔에서 `Lambda` 서비스로 이동해 `함수 생성` 버튼을 클릭합니다.
- 콘솔 우측 상단의 AWS 리전을 `미국 동부(버지니아 북부)`로 선택합니다. (Lambda@Edge는 Virginia Region에 생성해야 사용 가능합니다.)

### 1. 함수 이름 및 Runtime 설정

- `함수 이름`: 임의의 이름으로 입력합니다. (예: fwm-cf-embedder)
- `런타임`: `Node.js 24.x`를 선택합니다.
- `아키텍처`: `x86_64`를 사용합니다. `Additional settings`의 `ARM64 architecture` 토글은 끈 상태로 둡니다.

### 2. 실행 역할 설정

- `Additional settings`에서 `Custom execution role`을 켜고, `Configure custom execution role` 패널에서 이전 단계에서 생성한 IAM 역할을 선택한 후 `Save`를 클릭합니다.
- 화면 하단의 `함수 생성` 버튼을 클릭해 Lambda@Edge 함수를 생성합니다.

### 3. 샘플 코드 업로드 및 수정

- `Code source` 화면에서 `Update > Update from a .zip file`을 클릭해 [샘플 다운로드 페이지](https://docs.doverunner.com/content-security/forensic-watermarking/getting-started/fwm-downloads/)에서 다운받은 CloudFront Embedder zip 파일을 업로드합니다.

- 업로드된 샘플 코드 내용을 확인하고 아래와 같은 사항을 수정합니다.

> 아래 안내된 부분 이외의 소스를 수정할 경우, 오류가 발생할 수 있으니 주의하시기 바랍니다.

- `config.js` 소스에서 아래 테이블에 해당하는 변수의 값을 설정합니다.

| Name                | Required | Description      |
|:--------------------|:---------|:-----------------|
| `aesKey`            | True     | 도브러너 콘솔 사이트에서 제공하는 사이트 키 값을 입력합니다.                                                                                                                                                                                                                  |
| `type`              | True     | 전처리된 A/B 버전 세그먼트가 하나의 폴더에 함께 저장된 콘텐츠인 경우는 `unlabeled_a_variant`를 입력하고, 각각 `0`과 `1` 폴더로 나뉘어 패키징된 경우는 `directory_prefix`를 입력합니다. 하나의 폴더에 저장된 경우 B 버전 파일에는 `b.` 접두어가 붙습니다. 값을 설정하기 전에 스토리지의 출력 폴더 구조를 확인하시기 바랍니다. T&P 서비스로 전처리한 콘텐츠는 `0`과 `1` 폴더로 나뉘어 저장되므로 `directory_prefix`를 입력합니다. 폴더 구조와 값이 맞지 않으면 S3가 `403 AccessDenied`를 반환합니다. (기본값: `unlabeled_a_variant`) |
| `availableInterval` | True     | 워터마크 적용을 위해 요청된 URL에는 timestamp 값이 포함되어 있습니다. 본 항목은 해당 timestamp의 유효 기간을 체크하기 위한 값입니다. `0`으로 설정할 경우 timestamp 유효 기간을 체크하지 않습니다. 샘플 `config.js`에는 `60`으로 설정되어 있습니다. (단위: 분)                                                                                                                 |
| `prefixFolder`      | True    | A/B 버전 콘텐츠가 저장되어 있는 상위 폴더 명 설정<br/> - 기존 패키징 서비스로 패키징한 경우: `dldzkdpsxmdnjrtm` <br/> - 신규 T&P 서비스로 패키징한 경우: `wm-contents` <br/> 샘플 `config.js`에는 `["wm-contents"]`로 설정되어 있습니다.                                                          |
| `wmtPublicKey`      | False    | 세션 발급시 `wmt` 토큰 유형을 사용할 때 설정합니다. 도브러너 사이트에서 발급된 Akamai 공용 키를 사용하며, 헬프데스크에 요청할 수 있습니다.                                                                                                                                                               |
| `wmtPassword`       | False    | 세션 발급시 `wmt` 토큰 유형을 사용할 때 설정합니다. 도브러너 사이트에서 발급된 Akamai 암호를 사용하며, 헬프데스크에 요청할 수 있습니다.                                                                                                                                                                 |

> 임베더 2.10.0에 추가된 `syncSkipBit` 옵션은 `config.js`에서 설정하는 항목이 아닙니다. 임베더가 세션 URL의 페이로드(`sync_skip_bit`)에서 값을 읽으며, 값이 없으면 `-1`을 사용하기 때문에 별도로 설정할 필요가 없습니다.
    

- 저장한 후 `Action` 버튼의 `Publish new version`을 클릭하여 version을 생성합니다.

- 생성된 version이 포함된 ARN을 복사해 놓습니다. 우측 상단에 표시됩니다.
    - 예) `arn:aws:lambda:us-east-1:{계정넘버}:function:{lambda이름}:{version}`

> Lambda 콘솔의 `Actions` > `Capabilities` > `Deploy to Lambda@Edge` 메뉴에서 해당 버전을 배포(distribution)에 연결할 수도 있습니다.

## CloudFront 설정

Lambda@Edge는 기존 CloudFront 배포에 적용하거나, 새로 생성한 배포에 적용할 수 있습니다. 배포 생성 마법사에는 함수 연결 단계가 없기 때문에 두 경우 모두 배포를 생성한 후에 함수를 연결합니다.

### 배포 생성

워터마크 콘텐츠를 서비스하는 배포가 이미 있는 경우에는 [Lambda@Edge 적용](#lambdaedge-적용) 단계로 넘어갑니다.

AWS 콘솔에서 `CloudFront` 메뉴를 선택하고 `Create distribution`을 클릭한 후, 아래 순서대로 마법사를 진행합니다.

1. `Choose a plan`: `Pay as you go`를 선택합니다.
2. `Get started`: 배포 이름을 입력합니다.
3. `Specify origin`: A/B 버전 콘텐츠가 저장된 S3 버킷을 선택합니다. `Allow private S3 bucket access to CloudFront`는 선택된 상태로 둡니다. CloudFront가 OAC(Origin Access Control)를 생성하고 필요한 구문을 버킷 정책에 자동으로 추가합니다.
4. `Enable security`: AWS WAF 보안 보호 기능은 기본으로 활성화되어 있으며 추가 요금이 발생합니다. 서비스에 맞게 사용 여부를 선택합니다.
5. `Review`: 설정을 확인하고 배포를 생성합니다.

### Lambda@Edge 적용

AWS console 에 접속하여 `CloudFront` 메뉴 선택 후 lambda@Edge를 적용시킬 배포를 선택합니다.

#### 1. Behaviors 설정

- `Behaviors` 탭에서 `Default (*)` 동작을 선택한 후 `Edit` 버튼을 클릭합니다.

- `Function associations` 항목에서 `Viewer request`를 설정합니다.
	- Function type : `Lambda@Edge` 선택
	- Function ARN : Lambda@Edge 생성 과정에서 복사해 놓았던 ARN 입력

- `Save changes` 버튼을 클릭합니다.

#### 2. 설정 완료

배포 목록의 `Status`는 `Enabled`로 유지되며, 변경 사항이 배포되는 동안 `Last modified`에 `Deploying`이 표시됩니다. `Last modified`에 날짜가 표시되면 Lambda@Edge 적용이 완료되고 모든 설정이 끝납니다.

> 자세한 Lambda@Edge 관련 내용은 AWS 에서 제공하는 [CloudFront 가이드](https://docs.aws.amazon.com/ko_kr/AmazonCloudFront/latest/DeveloperGuide/lambda-at-the-edge.html)를 참조하시기 바랍니다.

### CORS 설정

플레이어가 CloudFront 배포와 다른 origin에서 실행되는 경우, 배포가 CORS 헤더를 반환해야 합니다. Lambda@Edge를 연결한 동작에 사용자 지정 응답 헤더 정책을 적용합니다.

- `Policies` > `Response headers`에서 응답 헤더 정책을 생성하고 `Cross-origin resource sharing (CORS)`를 활성화합니다. `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers`, `Access-Control-Allow-Methods`는 플레이어 환경에 맞게 설정하고(예: `All origins`, `All headers`, `All methods`), `Origin override`를 선택합니다.
- 해당 동작의 `Edit` 화면에서 `Response headers policy`로 생성한 정책을 선택하고 `Save changes`를 클릭합니다.

:::caution
관리형 정책인 `Managed-SimpleCORS`는 `Cache-Control: no-cache`가 포함된 요청(예: 브라우저 새로고침, 캐시를 끈 개발자 도구)에 `Access-Control-Allow-Origin` 없이 응답할 수 있습니다. 이 경우 브라우저가 CORS 오류로 응답을 차단해 재생에 실패하므로, `Origin override`를 선택한 사용자 지정 정책을 사용하시기 바랍니다.
:::

## 문제 해결

| 응답 | 원인 | 조치 |
|:---|:---|:---|
| `X-Cache: LambdaExecutionError from cloudfront`가 포함된 `503` | Lambda@Edge 함수가 실행되지 못한 경우입니다. 임베더 샘플이 지원하지 않는 런타임을 선택하면 이 오류가 발생합니다. | `Configuration` > `Runtime settings` > `Edit`에서 런타임을 `Node.js 24.x`로 변경하고, 새 버전을 게시한 후 새 버전 ARN을 동작에 연결합니다. |
| S3가 반환한 `403 AccessDenied` (`Server: AmazonS3`) | 임베더가 변환한 세그먼트 경로가 버킷에 존재하지 않는 경우입니다. 주로 `config.js`의 `type` 값이 폴더 구조와 맞지 않을 때 발생합니다. CloudFront에 `s3:ListBucket` 권한이 없기 때문에 S3는 `404` 대신 `403`을 반환합니다. | 폴더 구조를 확인해 `type`을 다시 설정하고, 새 버전을 게시한 후 새 버전 ARN을 동작에 연결합니다. |