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

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

Установка на Debian/Ubuntu

Эти документы применимы к APT пакету nginx-module-jwt, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-jwt
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия             | Компонент   | Архитектуры   |
|-------------|--------------------|-------------|---------------|
| debian      | bookworm           | main        | amd64, arm64  |
| debian      | bookworm-mainline  | main        | amd64, arm64  |
| debian      | trixie             | main        | amd64, arm64  |
| debian      | trixie-mainline    | main        | amd64, arm64  |
| ubuntu      | focal              | main        | amd64, arm64  |
| ubuntu      | focal-mainline     | main        | amd64, arm64  |
| ubuntu      | jammy              | main        | amd64, arm64  |
| ubuntu      | jammy-mainline     | main        | amd64, arm64  |
| ubuntu      | noble              | main        | amd64, arm64  |
| ubuntu      | noble-mainline     | main        | amd64, arm64  |

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

License

Это модуль 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

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

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

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

auth_jwt_key

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

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

auth_jwt_require

Синтаксис:   auth_jwt_require $value ... [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 поддерживает встроенные переменные: - $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 недействителен.