Модуль ngx_http_auth_jwt_module

Поддерживаемые алгоритмы
Пример конфигурации
Директивы
     auth_jwt
     auth_jwt_claim_set
     auth_jwt_header_set
     auth_jwt_key_file
     auth_jwt_key_request
     auth_jwt_leeway
     auth_jwt_type
     auth_jwt_require
Встроенные переменные

Модуль ngx_http_auth_jwt_module (1.11.3) предоставляет возможность авторизации клиента с проверкой предоставляемого JSON Web Token (JWT) при помощи указанных ключей. Модуль поддерживает JSON Web Signature (JWS), JSON Web Encryption (JWE) (1.19.7) и Nested JWT (1.21.0). Модуль может использоваться для настройки аутентификации OpenID Connect.

Модуль может быть скомбинирован с другими модулями доступа, такими как ngx_http_access_module, ngx_http_auth_basic_module и ngx_http_auth_request_module с помощью директивы satisfy.

Модуль доступен как часть коммерческой подписки.

Поддерживаемые алгоритмы

Модуль поддерживает следующие криптографические алгоритмы.

Алгоритмы JWS:

До версии 1.13.7 поддерживались только алгоритмы HS256, RS256 и ES256.

Алгоритмы JWE для шифрования содержимого (1.19.7):

Алгоритмы JWE для управления ключом (1.19.9):

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

location / {
    auth_jwt          "closed site";
    auth_jwt_key_file conf/keys.json;
}

Директивы

Синтаксис: auth_jwt строка [token=$переменная] | off;
Умолчание:
auth_jwt off;
Контекст: http, server, location, limit_except

Включает проверку JSON Web Token. Заданная строка используется в качестве realm. В значении параметра допустимо использование переменных.

Необязательный параметр token задаёт переменную, содержащую JSON Web Token. По умолчанию JWT передаётся в заголовке “Authorization” в качестве Bearer Token. JWT может также передаваться как кука или часть строки запроса:

auth_jwt "closed site" token=$cookie_auth_token;

Специальное значение off отменяет действие унаследованной с предыдущего уровня конфигурации директивы auth_jwt.

Синтаксис: auth_jwt_claim_set $переменная имя ...;
Умолчание:
Контекст: http

Эта директива появилась в версии 1.11.10.

Устанавливает переменную в параметр JWT claim, определяемый именами ключей. Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми.

auth_jwt_claim_set $email info e-mail;
auth_jwt_claim_set $job info "job title";

До версии 1.13.7 можно было указать лишь одно имя, результат для массивов был не определён.

Значения переменных для tokens, зашифрованных при помощи JWE, доступны только после дешифрования, которое происходит в Access-фазе.

Синтаксис: auth_jwt_header_set $переменная имя ...;
Умолчание:
Контекст: http

Эта директива появилась в версии 1.11.10.

Устанавливает переменную в параметр заголовка JOSE, определяемый именами ключей. Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми.

До версии 1.13.7 можно было указать лишь одно имя, результат для массивов был не определён.

Синтаксис: auth_jwt_key_file файл;
Умолчание:
Контекст: http, server, location, limit_except

Задаёт файл в формате JSON Web Key Set для проверки подписи JWT. В значении параметра допустимо использование переменных.

На одном уровне может быть указано несколько директив auth_jwt_key_file (1.21.1):

auth_jwt_key_file conf/keys.json;
auth_jwt_key_file conf/key.jwk;

Если хотя бы один из указанных ключей не может быть загружен или обработан, nginx вернёт ошибку 500 (Internal Server Error).

Синтаксис: auth_jwt_key_request uri;
Умолчание:
Контекст: http, server, location, limit_except

Эта директива появилась в версии 1.15.6.

Позволяет получать файл в формате JSON Web Key Set из подзапроса для проверки подписи JWT и задаёт URI, на который будет отправлен подзапрос. В значении параметра допустимо использование переменных. Для предотвращения дополнительных затрат на проверку файл рекомендутеся кэшировать.

proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m;

server {
    ...

    location / {
        auth_jwt             "closed site";
        auth_jwt_key_request /jwks_uri;
    }

    location = /jwks_uri {
        internal;
        proxy_cache foo;
        proxy_pass  http://idp.example.com/keys;
    }
}

На одном уровне может быть указано несколько директив auth_jwt_key_request (1.21.1):

auth_jwt_key_request /jwks_uri;
auth_jwt_key_request /jwks2_uri;

Если хотя бы один из указанных ключей не может быть загружен или обработан, nginx вернёт ошибку 500 (Internal Server Error).

Синтаксис: auth_jwt_leeway время;
Умолчание:
auth_jwt_leeway 0s;
Контекст: http, server, location

Эта директива появилась в версии 1.13.10.

Задаёт максимально допустимое отклонение времени для компенсации расхождения часов при проверке JWT claims exp и nbf.

Синтаксис: auth_jwt_type signed | encrypted | nested;
Умолчание:
auth_jwt_type signed;
Контекст: http, server, location, limit_except

Эта директива появилась в версии 1.19.7.

Задаёт ожидаемый тип JSON Web Token: JWS (signed), JWE (encrypted) или подписанный и затем зашифрованный Nested JWT (nested) (1.21.0).

Синтаксис: auth_jwt_require значение ...;
Умолчание:
Контекст: http, server, location, limit_except

Эта директива появилась в версии 1.21.2.

Задаёт дополнительные условия для проверки JWT. В качестве значения можно использовать текст, переменные и их комбинации. Для успешной аутентификации необходимо, чтобы значение всех строковых параметров было непустое или не равно “0”.

map $jwt_claim_iss $valid_jwt_iss {
    "good" 1;
}
...

auth_jwt_require $valid_jwt_iss;

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

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

$jwt_header_имя
возвращает значение указанного заголовка JOSE
$jwt_claim_имя
возвращает значение указанной JWT claim

Для вложенных claim, а также claim, содержащих точку (“.”), значение переменной вычислить невозможно, следует использовать директиву auth_jwt_claim_set.

Значения переменных для tokens, зашифрованных при помощи JWE, доступны только после дешифрования, которое происходит в Access-фазе.

$jwt_payload
возвращает расшифрованную полезную нагрузку (payload) верхнего уровня для вложенных или зашифрованных токенов (1.21.2). Для вложенных токенов возвращает внутренний JWS токен. Для зашифрованных токенов возвращает JSON с claims.