Перейти к содержанию

jwt: Модуль JWT для NGINX

Установка

Вы можете установить этот модуль в любой дистрибутив на базе 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
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.4, выпущенный 3 февраля 2026 года.

Модуль аутентификации JWT для Nginx

License

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

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

Docker-образ:

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

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

Предварительно собранные пакеты (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; # Ваш ключ в виде шестнадцатеричной строки
        auth_jwt     off;

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

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

        # Ключи JWT наследуются от предыдущего уровня конфигурации
        # но вы можете иметь разные ключи для разных местоположений
        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

Syntax:  auth_jwt $variable | on | off;
Default: auth_jwt off;
Context: http, server, location

Включает валидацию JWT.

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

auth_jwt_key

Syntax:  auth_jwt_key value [encoding];
Default: ——
Context: http, server, location

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

auth_jwt_alg

Syntax:  auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Default: auth_jwt_alg any;
Context: http, server, location

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

auth_jwt_require

Syntax:  auth_jwt_require $value ... [error=401 | 403];
Default: ——
Context: 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 поддерживает встроенные переменные:

  • $jwtheadername возвращает значение указанного заголовка
  • $jwtclaimname возвращает значение указанного утверждения
  • $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; # Ваш ключ в виде шестнадцатеричной строки
        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.