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.3, выпущенный 14 марта 2025 года.

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

Это модуль NGINX для проверки действительности JWT. Этот модуль предназначен быть как можно более легким и простым: - Образ Docker, основанный на официальном Dockerfile nginx (alpine). - Легкий образ (~400KB больше, чем официальный).

Конфигурация модуля:

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

## 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 поддерживает встроенные переменные: - $jwt_header_name возвращает значение указанного заголовка - $jwt_claim_name возвращает значение указанного утверждения - $jwt_headers возвращает заголовки - $jwt_payload возвращает полезную нагрузку

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

Образ:

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

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

Просто создайте свой образ на основе сгенерированного образа 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.