← Документация WAF / custom-rules / use-cases

Настройка аутентификации по токену

Токенная аутентификация позволяет ограничить доступ к документам, файлам и медиа избранным пользователям без необходимости регистрации. Это помогает защитить платный/ограниченный контент от паразитного скачивания и несанкционированного распространения.

Настроить аутентификацию по токену можно двумя способами: через Cloudflare Workers или через пользовательские правила.

Обратитесь к следующим ресурсам Cloudflare Workers с двумя разными реализациями аутентификации по токену:

• Подпись запросов (пример).
• Аутентификация с помощью заголовков (шаблон).

Чтобы начать работу с Workers, см. Шаблоны.

Используйте язык Rules is_timed_hmac_valid_v0() для валидации токенов HMAC (hash-based message authentication code) в выражении пользовательского правила.

Чтобы проверить аутентификацию по токену, создайте пользовательское правило вызовом is_timed_hmac_valid_v0() (функция) в выражении правила. Можно использовать действие, например Block.

Этот пример иллюстрирует правило, блокирующее любого посетителя, не прошедшего валидацию HMAC-ключа на определённом имени хоста и пути URL. Для аутентификации по токену требуются:

• Секретный ключ для генерации и валидации HMAC (например, mysecrettoken)
• Путь, который вы хотите аутентифицировать (например, downloads.example.com/images/cat.jpg)
• Имя параметра строки запроса, содержащего токен (например, verify)
• Время жизни токена в секундах (например, 3 часа = 10 800 секунд)

Рассмотрим следующий пример URL:

downloads.example.com/images/cat.jpg?verify=1484063787-9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D

Где:

• /images/cat.jpg представляет путь к ресурсу — HMAC-сообщение для аутентификации.
• ?verify= — разделитель между путём к ресурсу и меткой времени выдачи HMAC-токена.
• 1484063787 представляет метку времени выдачи токена в формате UNIX-времени в секундах.
• 9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D — это MAC в кодировке Base64.

Выражение пользовательского правила будет похоже на следующее:

(http.host eq "downloads.example.com" and not is_timed_hmac_valid_v0("mysecrettoken", http.request.uri, 10800, http.request.timestamp.sec, 8))

Компоненты этого примера пользовательского правила (для приведённого выше примера URL):

• Секретный ключ токена = mysecrettoken
• Время жизни токена = 10800 (10,800 секунд = 3 часа)
• http.request.uri = /images/cat.jpg?verify=1484063787-9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D
• http.request.timestamp.sec = 1484071925 (например)
• Длина разделителя: len("?verify=") = 8

is_timed_hmac_valid_v0() сравнивает значение MAC, сгенерированного с использованием mysecrettoken секретный ключ со значением, закодированным в http.request.uri.

Если значения MAC совпадают и срок действия токена ещё не истёк согласно следующей формуле:

http.request.timestamp.sec < (<TIMESTAMP_ISSUED> + 10800)

Тогда токен действителен, и is_timed_hmac_valid_v0() (функция) возвращает true.

Следующие примеры показывают, как генерировать токены на вашем сервере-источнике для пути, проверяемого пользовательским правилом из предыдущего раздела:

import hmac
import base64
import time
import urllib.parse
from hashlib import sha256

message = "/images/cat.jpg"
secret = "mysecrettoken"
separator = "verify"
timestamp = str(int(time.time()))
digest = hmac.new((secret).encode('utf8'), "{}{}".format(message, timestamp).encode('utf8'), sha256)
token = urllib.parse.quote_plus(base64.b64encode(digest.digest()))
print("{}={}-{}".format(separator, timestamp, token))

import hmac
import base64
import time
import urllib
from hashlib import sha256

message = "/images/cat.jpg"
secret = "mysecrettoken"
separator = "verify"
timestamp = str(int(time.time()))
digest = hmac.new(secret, message + timestamp, sha256)
param = urllib.urlencode({separator: '%s-%s' % (timestamp, base64.b64encode(digest.digest()))})
print(param)

<?php
$message = "/images/cat.jpg";
$secret = "mysecrettoken";
$separator = "verify";
$timestamp = time();
$token = urlencode(base64_encode(hash_hmac("sha256", $message . $timestamp, $secret, true)));
echo("{$separator}={$timestamp}-{$token}");

Будет сгенерирован URL-параметр, подобный следующему:

verify=1484063787-9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D

Этот параметр необходимо добавить к защищаемому URL:

/images/cat.jpg?verify=1484063787-9JQB8vP1z0yc5DEBnH6JGWM3mBmvIeMrnnxFi3WtJLE%3D

Если вы на плане Enterprise, можно проверить, корректно ли генерируются URL на исходном сервере, следующим образом:

1. Установите действие пользовательского правила Log.
2. Проверьте выборочные логи в Security Events.

Один и тот же секретный ключ можно использовать для защиты нескольких URI-путей.

Это показано в предыдущем примере, где http.request.uri передаётся как MessageMAC аргумент в функцию валидации.

Поскольку http.request.uri содержит путь к ресурсу и это значение извлекается для каждого запроса, функция валидации рассматривает все URI запросов к downloads.example.com с использованием того же секретного ключа.

Обратите внимание: хотя один и тот же секретный ключ можно использовать для аутентификации нескольких путей, HMAC-токен необходимо генерировать для каждого уникального сообщения, которое вы хотите аутентифицировать.

Вы можете защитить целый префикс пути URI фиксированной длины одной HMAC-подписью (с тем же секретом). Для этого передайте префикс пути URI (вместо полного пути URI) и исходную строку запроса в качестве MessageMAC аргумент для is_timed_hmac_valid_v0() функции.

Используйте substring(), чтобы получить префикс из полного пути URI.

В следующем примере префикс пути URI, требующий одной HMAC-подписи, всегда имеет длину 51 символ (x — символ-заполнитель):

/case-studies/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/

В этом случае вам понадобилась бы отдельная HMAC-подпись для каждого различного префикса пути URI длиной 51 символ.

Если вы хотите блокировать запросы к файлам кейсов, не прошедшие проверку HMAC, можно создать пользовательское правило наподобие следующего:

  (http.host eq "downloads.example.com" and starts_with(http.request.uri.path, "/case-studies") and not is_timed_hmac_valid_v0("mysecrettoken", concat(substring(http.request.uri.path, 0, 51), "?", http.request.uri.query), 10800, http.request.timestamp.sec, 1))

Примеры путей URI допустимых входящих запросов:

/case-studies/12345678-90ab-4cde-f012-3456789abcde/foobar-report.pdf?1755877101-5WOroVcDINdl2%2BQZxZFHJcJ6l%2Fep4HGIrX3DtSXzWO0%3D
/case-studies/12345678-90ab-4cde-f012-3456789abcde/acme-corp.pdf?1755877101-5WOroVcDINdl2%2BQZxZFHJcJ6l%2Fep4HGIrX3DtSXzWO0%3D
/case-studies/768bf477-22d5-4545-857d-b155510119ff/another-company-report.pdf?1755878057-jeMS5S1F3MIgxvL61UmiX4vODiWtuLfcPV6q%2B0Y3Rig%3D

Первые два пути URI могут использовать одну и ту же HMAC-подпись, потому что у них общий префикс из 51 символа (/case-studies/12345678-90ab-4cde-f012-3456789abcde/), который проверяется пользовательским правилом.

Третьему URI-пути нужна другая HMAC-подпись, поскольку префикс отличается.