署名付き URL による CDN コンテンツの保護
ファイルを公開せずに、アプリケーションでダウンロードを許可できます。AWS CloudFront では、サーバーでオブジェクトの URL に署名し、有効期限を設定します。この手順では、実行可能な TypeScript の署名プログラムと、ほかのアクセス経路を閉じたまま、URL から意図したバイト列が配信されることを確認する検証プログラムを紹介します。
CDN のセキュリティと署名付き URL の仕組み
署名付き URL は、所有者に権限を与える認証情報です。受け取った人は誰でも、有効期限まで利用できます。URL の発行前にアプリケーションでユーザーの権限を確認し、クライアントから渡された任意の URL に署名するのではなく、サーバー側で対象のオブジェクトを選択してください。
CloudFront は、一致するキャッシュビヘイビアに関連付けられた信頼済みキーグループの公開鍵で署名を検証します。対応する秘密鍵はサーバー側で保持します。この例では既定ポリシーを使い、アクセス対象を単一の URL と終了時刻に限定しますが、ダウンロードできる人をリクエストした本人に限定するものではありません。CloudFront の署名付き URL の仕組みを参照してください。
ビューワーの認可とオリジンへのアクセスの分離
ふたつの制御を整合させる必要があります。信頼済みキーグループは、ビューワーから CloudFront へのリクエストを制御します。非公開の S3 オリジンでは、オリジンアクセスコントロール(OAC)とバケットポリシーにより CloudFront にオブジェクトの読み取りを許可し、匿名の S3 直接リクエストは引き続き拒否します。片方の制御だけを設定しても、両方の保護は成立しません。
このページでは、アプリケーションの署名プログラムに焦点を当てます。インフラの背景については、S3 と CloudFront による画像 CDN ガイドを参照してください。オリジンポリシーと、ディストリビューション固有の AWS:SourceArn 条件の設定には、AWS の OAC 設定手順を使用してください。通常の S3 バケットオリジンを使用してください。S3 ウェブサイトエンドポイントでは OAC を使えません。
実装の前提条件
署名プログラムの実行前に、次を準備してください。
- デプロイ済みの CloudFront ディストリビューション、HTTPS のオブジェクト URL、S3 内の既知の非公開オブジェクト。後述のバイト比較に使うため、そのオブジェクトのローカルコピーも保持してください。
- PEM 形式の専用 RSA-2048 キーペア。公開鍵を CloudFront にアップロードして信頼済みキーグループに追加し、オブジェクトを配信するキャッシュビヘイビアにそのグループを関連付けてください。AWS のキーペアと信頼済みキーグループの手順に従ってください。
- 公開鍵の ID と、サーバーアカウントだけが読み取れる対応する秘密鍵ファイル。このキー ID は、IAM アクセスキーでもキーグループ ID でもありません。ローカルでの署名には、AWS アクセスキーも SDK の認証情報プロファイルも必要ありません。
- S3 ブロックパブリックアクセスを有効にした非公開バケット、オリジンリクエストに常に署名する設定の OAC、このディストリビューションに読み取りアクセスを許可するバケットポリシー。デプロイが完了してからテストしてください。署名サーバーの時刻は同期させておいてください。
- Node.js 26 と、別途インストールした Corepack。メンテナンスされている Node.js のパッチリリースを使用してください。再現用のバージョンは
Node.js 26.8.1、Yarn 4.12.0、
@aws-sdk/cloudfront-signer3.1069.0 です。これらはテスト済みのバージョンであり、必須の最低バージョンではありません。
AWS CloudFront による署名付き URL の実装
書き込み可能なディレクトリから、Bash でこのセットアップを実行してください。cloudfront-url-demo を作成し、シェルの現在のディレクトリは元のまま維持します。既存のディレクトリは拒否されます。プロジェクトを上書きせず、新しい名前を選んでください。子プロジェクトのロックファイルとローカルの Yarn 設定により、Plug’n’Play を使用する場合も含め、親ワークスペースからパッケージのインストールを分離します。
(
command -v node >/dev/null &&
command -v corepack >/dev/null &&
mkdir cloudfront-url-demo &&
cd cloudfront-url-demo &&
printf '%s\n' '{"private":true,"type":"module","packageManager":"yarn@4.12.0","dependencies":{"@aws-sdk/cloudfront-signer":"3.1069.0"}}' > package.json &&
printf '%s\n' 'nodeLinker: node-modules' 'ignorePath: true' 'enableGlobalCache: false' 'plugins: []' > .yarnrc.yml &&
touch yarn.lock &&
corepack yarn install
)
インストールに失敗した場合は、プロジェクトを残し、パッケージマネージャーのエラーを調べてください。原因を修正したら、corepack yarn install を
cloudfront-url-demo 内で実行してください。ディレクトリ作成の手順は繰り返さないでください。次のプログラム全体を cloudfront-url-demo/signed-url.mts として保存してください。
import { createPrivateKey } from 'node:crypto'
import { readFile } from 'node:fs/promises'
import { isAbsolute } from 'node:path'
import { getSignedUrl } from '@aws-sdk/cloudfront-signer'
async function main(): Promise<void> {
const args = process.argv.slice(2)
const [resourceUrl, lifetime = '300'] = args
const keyPairId = process.env.CLOUDFRONT_KEY_PAIR_ID
const keyFile = process.env.CLOUDFRONT_PRIVATE_KEY_FILE
if (args.length < 1 || args.length > 2 || !resourceUrl || !keyPairId || !keyFile) {
throw new Error('Missing configuration')
}
if (!/^[A-Za-z0-9]+$/u.test(keyPairId) || !isAbsolute(keyFile)) {
throw new Error('Invalid key configuration')
}
const url = new URL(resourceUrl)
if (
url.protocol !== 'https:' || url.username || url.password || url.search || url.hash ||
url.href !== resourceUrl
) {
throw new Error('Use an exact HTTPS object URL without a query or fragment')
}
const seconds = Number(lifetime)
if (!/^\d+$/u.test(lifetime) || !Number.isSafeInteger(seconds) || seconds < 1 || seconds > 3600) {
throw new Error('Lifetime must be an integer from 1 to 3600 seconds')
}
const privateKey = await readFile(keyFile, 'utf8')
const key = createPrivateKey(privateKey)
if (key.asymmetricKeyType !== 'rsa' || key.asymmetricKeyDetails?.modulusLength !== 2048) {
throw new Error('Use an RSA-2048 private key')
}
const signedUrl = getSignedUrl({
url: resourceUrl,
keyPairId,
privateKey,
dateLessThan: new Date(Date.now() + seconds * 1000).toISOString(),
})
process.stdout.write(`${signedUrl}\n`)
}
main().catch(() => {
console.error('Could not sign URL. Check the HTTPS URL, key ID, RSA-2048 PEM file, and 1–3600 second lifetime.')
process.exitCode = 1
})
設定値をみっつとも自身の値に置き換えてください。第2引数は秒単位の有効期間で、省略すると 300 秒になります。この例では、意図的にクエリ文字列やフラグメントを含まない正確な HTTPS URL のみを受け付け、有効期間の上限を一時間にしています。
CLOUDFRONT_KEY_PAIR_ID='YOUR_PUBLIC_KEY_ID' \
CLOUDFRONT_PRIVATE_KEY_FILE='/absolute/path/to/private-key.pem' \
node cloudfront-url-demo/signed-url.mts \
'https://YOUR_DISTRIBUTION.cloudfront.net/private/guide.pdf' 300
成功すると、標準出力に URL をひとつ出力します。設定が無効な場合、鍵が読み取れないか形式が不正な場合、または有効期間が無効な場合は、URL を出力せず、ゼロ以外の終了コードで終了します。対応しない鍵でも、形式が正しければローカルでは署名できることがあります。デプロイ済みのビヘイビアがその鍵を信頼するかどうかを確認できるのは、CloudFront だけです。
テストと検証
署名付き文字列を生成できても、CDN でアクセス制御が機能する証明にはなりません。次を cloudfront-url-demo/verify-private.mts として保存してください。署名プログラムを実行し、レスポンス全体をダウンロードしてローカルの元ファイルと比較してから、拒否されるべき 4 つのアクセス経路をテストします。各 HTTP 検証にはレスポンス本文の取得も含めて
15 秒の制限時間があり、リダイレクトが発生すると検証は失敗します。
import assert from 'node:assert/strict'
import { execFileSync } from 'node:child_process'
import { readFile } from 'node:fs/promises'
import { setTimeout as delay } from 'node:timers/promises'
import { fileURLToPath } from 'node:url'
async function main(): Promise<void> {
const [objectUrl, directS3Url, originalFile, ...extra] = process.argv.slice(2)
assert(objectUrl && directS3Url && originalFile && extra.length === 0, 'Supply both URLs and the original file')
const expected = await readFile(originalFile)
const signerFile = fileURLToPath(new URL('./signed-url.mts', import.meta.url))
function sign(seconds: number): string {
return execFileSync(process.execPath, [signerFile, objectUrl, String(seconds)], {
encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
}).trim()
}
async function check(url: string, allowed: boolean): Promise<void> {
const response = await fetch(url, { redirect: 'error', signal: AbortSignal.timeout(15_000) })
const bytes = Buffer.from(await response.arrayBuffer())
if (allowed) {
assert.equal(response.status, 200, 'Valid URL was denied')
assert.equal(Buffer.compare(bytes, expected), 0, 'Downloaded bytes differ from the original')
} else {
assert.equal(response.status, 403, 'Private access was not denied')
assert.notEqual(Buffer.compare(bytes, expected), 0, 'Denied response disclosed the object')
}
}
const valid = sign(300)
await check(valid, true)
await check(objectUrl, false)
const tampered = new URL(valid)
const signature = tampered.searchParams.get('Signature')
assert(signature, 'Missing signature')
tampered.searchParams.set('Signature', `${signature[0] === 'A' ? 'B' : 'A'}${signature.slice(1)}`)
await check(tampered.href, false)
const expired = sign(1)
await delay(Math.max(0, Number(new URL(expired).searchParams.get('Expires')) * 1000 - Date.now()) + 1500)
await check(expired, false)
await check(directS3Url, false)
console.log('Private delivery checks passed.')
}
main().catch(() => {
console.error('Private delivery check failed. Check the object bytes and the CloudFront and S3 access configuration.')
process.exitCode = 1
})
CloudFront のオブジェクト URL、同じオブジェクトの S3 直接 URL、ローカルの元ファイルを指定して実行してください。
CLOUDFRONT_KEY_PAIR_ID='YOUR_PUBLIC_KEY_ID' \
CLOUDFRONT_PRIVATE_KEY_FILE='/absolute/path/to/private-key.pem' \
node cloudfront-url-demo/verify-private.mts \
'https://YOUR_DISTRIBUTION.cloudfront.net/private/guide.pdf' \
'https://YOUR_BUCKET.s3.us-east-1.amazonaws.com/private/guide.pdf' \
'/absolute/path/to/original-guide.pdf'
スクリプトが Private delivery checks passed. と表示するのは、意図したバイト列を受信し、拒否されるべき 4 つのリクエストがすべて、そのバイト列を漏らさずに 403 を返した場合だけです。有効期限の検証では、期限が切れた後に新しいリクエストを開始します。CloudFront はリクエスト開始時に有効期限を確認します。その時刻を過ぎても、すでに進行中のダウンロードは終了しません。
よくある問題のトラブルシューティング
有効なリクエストが失敗する場合は、まずデプロイ済みのキャッシュビヘイビア、信頼済みグループの公開鍵 ID、対応する秘密鍵を確認してください。403 だけでは、不正な署名とオリジンアクセスの問題を区別できません。オブジェクトのパス、OAC、バケットポリシーも確認してください。AWS の 403 トラブルシューティングガイドで、これらの確認手順を説明しています。
有効なリクエストが異なるバイト列を返す場合は、オブジェクト URL とローカルの元ファイルを調べ、古いオブジェクトがキャッシュされていないか確認してください。署名なしのリクエストが成功する場合は、そのパスに実際に一致するキャッシュビヘイビアを調べてください。S3 への直接アクセスが成功する場合は、ダウンロードリンクを発行する前にバケットのアクセスポリシーを修正してください。この検証プログラムがテストするのは、この単一のオブジェクトとディストリビューションのパスです。ほかの保護対象のビヘイビアについても繰り返し実行してください。
セキュリティのベストプラクティス
秘密鍵をブラウザーバンドル、ソース管理、ログに含めないでください。サーバーのシークレットストレージから、アクセスを制限したファイルとしてマウントしてください。署名付き URL も秘密情報として扱い、分析データ、リクエストログ、サポートメッセージへの記録を避けてください。HTTPS 経由で、権限のある受信者だけに共有してください。
ダウンロードを開始するための十分な時間を確保しつつ、有効期間は短くしてください。鍵をローテーションする場合は、署名プログラムを変更する前に、新しい公開鍵を古い鍵と併せてデプロイしてください。発行済みの URL を失効させる意図がない限り、それらの有効期限が切れるまで古い鍵を保持してください。AWS の鍵のローテーション手順では、この併存期間について説明しています。
非公開配信の検証に合格したら、署名プログラムをアプリケーションの認可判定と連携させてください。認証済みユーザーにアクセス権があるオブジェクトに対してのみ URL を返し、ディストリビューションやオリジンポリシーを変更するときも、同じ配信検証を続けてください。
