Модуль ngx_http_auth_jwt_module

• Поддерживаемые алгоритмы
• Пример конфигурации
• Директивы
• auth_jwt
• auth_jwt_claim_set
• auth_jwt_header_set
• auth_jwt_key_cache
• 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.

Данный модуль доступен в рамках нашей коммерческой подписки.

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

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

Алгоритмы JWS:

• HS256, HS384, HS512
• RS256, RS384, RS512
• ES256, ES384, ES512
• EdDSA (подписи Ed25519 и Ed448) (1.15.7)

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

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

• A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
• A128GCM, A192GCM, A256GCM

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

• A128KW, A192KW, A256KW
• A128GCMKW, A192GCMKW, A256GCMKW
• dir - прямое использование общего симметричного ключа в качестве ключа шифрования содержимого
• RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0)

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

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

Директивы

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

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

auth_jwt "closed site" token=$cookie_auth_token;

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

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

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

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

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

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

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

Включает или отключает кэширование ключей, полученных из файла file или из подзапроса subrequest, и устанавливает время кэширования. Кэширование ключей, полученных из переменных, не поддерживается. По умолчанию кэширование ключей отключено.

Указывает file в формате 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 (Внутренняя ошибка сервера).

Разрешает извлечение файла 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 (Внутренняя ошибка сервера).

Устанавливает максимальное допустимое значение для компенсации смещения часов при проверке JWT-утверждений exp и nbf.

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

Указывает дополнительные проверки для валидации JWT. Значение может содержать текст, переменные и их комбинацию и должно начинаться с переменной (1.21.7). Авторизация будет успешной только если все значения не пустые и не равны “0”.

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

auth_jwt_require $valid_jwt_iss;

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

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

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

$jwt_header_name

возвращает значение указанного JOSE заголовка

$jwt_claim_name

возвращает значение указанного JWT утверждения

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

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

$jwt_payload

возвращает дешифрованный верхнеуровневый payload токенов nested или encrypted (1.21.2). Для вложенных токенов возвращает вложенный JWS токен. Для зашифрованных токенов возвращает JSON с утверждениями.