jwt: NGINX JWT модуль

Установка

Вы можете установить этот модуль в любом дистрибутиве на основе RHEL, включая, но не ограничиваясь:

• RedHat Enterprise Linux 7, 8, 9 и 10
• CentOS 7, 8, 9
• AlmaLinux 8, 9
• Rocky Linux 8, 9
• Amazon Linux 2 и Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 и Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-jwt

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-jwt

Включите модуль, добавив следующую строку в начало /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

Этот документ описывает nginx-module-jwt v3.4.6, выпущенный 01 августа 2026 года.

---

Nginx jwt auth module

Это NGINX модуль для проверки действительности JWT. Модуль предназначен быть максимально легким и простым:

• Docker образ на основе официального nginx Dockerfile (alpine).
• Легкий образ (~на 400KB больше официального).

Быстрый старт:

Docker образ:

Образ создается с помощью Github Actions (см. nginx-jwt-module:latest)

docker pull ghcr.io/max-lt/nginx-jwt-module:latest

Также доступен более легкий вариант на основе nginx:alpine-slim (без дополнительных динамических модулей nginx, таких как njs, image-filter, xslt или geoip):

docker pull ghcr.io/max-lt/nginx-jwt-module:latest-slim

Готовые пакеты (Ubuntu / Debian)

Готовые пакеты для этого модуля свободно доступны в репозитории GetPageSpeed:

# Добавьте репозиторий (пример для Ubuntu - замените 'ubuntu' и 'jammy' на ваш дистрибутив)
echo "deb [signed-by=/etc/apt/keyrings/getpagespeed.gpg] https://extras.getpagespeed.com/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/getpagespeed-extras.list

# nginx.conf
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

http {
    server {
        auth_jwt_key "0123456789abcdef" hex; # Ваш ключ в виде hex-строки
        auth_jwt     off;

        # Метод аутентификации по умолчанию - заголовок "Authentication"
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Но вы можете использовать cookie вместо этого
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # Ключи JWT наследуются с предыдущего уровня конфигурации,
        # но вы можете использовать разные ключи для разных location
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Ваш ключ в виде utf8-строки
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # Ваш ключ из PEM-файла
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

Примечание: не забудьте подключить модуль в основном контексте:

load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

Директивы:

auth_jwt

Синтаксис: auth_jwt $variable | on | off;
По умолчанию: auth_jwt off;
Контекст: http, server, location

Включает проверку JWT.

Значение auth_jwt $variable может использоваться для задания пользовательского способа получения JWT, например, для получения из cookie вместо заголовка Authentication по умолчанию: auth_jwt $cookie_MyCookieName;

---

auth_jwt_key

Синтаксис: auth_jwt_key значение [кодировка];
По умолчанию: ——
Контекст: http, server, location

Задает ключ для проверки подписи JWT (должен быть шестнадцатеричным).
Опция encoding может быть hex | utf8 | base64 | file (по умолчанию utf8).
Опция file требует, чтобы значение было допустимым путем к файлу (указывающим на PEM-кодированный ключ).

---

auth_jwt_alg

Синтаксис: auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
По умолчанию: auth_jwt_alg any;
Контекст: http, server, location

Указывает, какой алгоритм сервер ожидает получить в JWT.

Токены, подписанные алгоритмом HMAC (HS256, HS384, HS512), всегда отклоняются, когда ключ является PEM-ключом, независимо от значения этой директивы: публичный ключ не является секретом, поэтому любой другой человек мог бы использовать его для подписи токена, который сервер бы принял. Тем не менее, рекомендуется явно указывать ожидаемый алгоритм.

---

auth_jwt_require

Синтаксис: auth_jwt_require $значение ... [error=401 | 403];
По умолчанию: ——
Контекст: http, server, location

Задает дополнительные проверки для валидации JWT. Аутентификация будет успешной только если все значения не пустые и не равны «0».

Эти директивы наследуются с предыдущего уровня конфигурации только в том случае, если на текущем уровне не определены директивы auth_jwt_require.

Если любая из проверок не пройдена, возвращается код ошибки 401. Необязательный параметр error позволяет переопределить код ошибки на 403.

Пример:

# server.conf

map $jwt_claim_role $jwt_has_admin_role {
    \"admin\"  1;
}

map $jwt_claim_scope $jwt_has_restricted_scope {
    \"restricted\"  1;
}

server {
  # ...

  location /auth-require {
    auth_jwt_require $jwt_has_admin_role error=403;
    # ...
  }

  location /auth-compound-require {
    auth_jwt_require $jwt_has_admin_role $jwt_has_restricted_scope error=403;
    # ...
  }
}

Обратите внимание, что поскольку $jwt_claim_ возвращает JSON-кодированное значение, мы должны проверять \"value\" (а не value)

Встроенные переменные:

Модуль ngx_http_auth_jwt_module поддерживает встроенные переменные:

• $jwtheaderимя возвращает указанное значение заголовка
• $jwtclaimимя возвращает указанное значение claim
• $jwt_headers возвращает заголовки
• $jwt_payload возвращает полезную нагрузку

Обратите внимание, что поскольку все возвращаемые значения JSON-кодированы, строки будут окружены символом "

Расширение вашего Docker образа:

Просто создайте свой образ на основе сгенерированного Github

FROM ghcr.io/max-lt/nginx-jwt-module:latest

# Скопируйте вашу конфигурацию nginx
# Не забудьте включить этот модуль в вашу конфигурацию
# load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
COPY my-nginx-conf /etc/nginx

EXPOSE 8000

STOPSIGNAL SIGTERM

CMD ["nginx", "-g", "daemon off;"]

Или используйте предоставленный образ напрямую

docker run -p 80:80 \
  -v ./nginx.conf:/etc/nginx/nginx.conf \
  ghcr.io/max-lt/nginx-jwt-module

или

docker build -f Dockerfile -t jwt-nginx .

### Тестирование:

#### Использование по умолчанию:

```bash
make test # Соберет тестовый образ и запустит набор тестов

Примеры конфигураций:

В этом разделе мы рассмотрим несколько примеров использования этого модуля.

Перенаправление на страницу входа, если JWT недействителен:

load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

# ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # Ваш ключ в виде hex-строки
        auth_jwt     off;

        location @login_err_redirect {
            return 302 $scheme://$host:$server_port/login?redirect=$request_uri;
        }

        location /secure/ {
            auth_jwt on;
            error_page 401 = @login_err_redirect;
        }

        location / {
            return 200 "OK";
        }
    }
}

При попытке curl -i http://localhost/secure/path?param=value будет возвращен редирект 302 на /login?redirect=/secure/path?param=value, если JWT недействителен.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-jwt.