Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_auth_jwt_module.xml @ 2906:4eb241b57f83
Linux packages: added Ubuntu 22.10 "kinetic".
author | Konstantin Pavlov <thresh@nginx.com> |
---|---|
date | Tue, 25 Oct 2022 15:26:00 +0400 |
parents | 8bd6f772005f |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_http_auth_jwt_module" link="/ru/docs/http/ngx_http_auth_jwt_module.html" lang="ru" rev="12"> <section id="summary"> <para> Модуль <literal>ngx_http_auth_jwt_module</literal> (1.11.3) предоставляет возможность авторизации клиента с проверкой предоставляемого <link url="https://datatracker.ietf.org/doc/html/rfc7519">JSON Web Token</link> (JWT) при помощи указанных ключей. Модуль поддерживает <link url="https://datatracker.ietf.org/doc/html/rfc7515">JSON Web Signature</link> (JWS), <link url="https://datatracker.ietf.org/doc/html/rfc7516">JSON Web Encryption</link> (JWE) (1.19.7) и Nested JWT (1.21.0). Модуль может использоваться для настройки аутентификации <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>. </para> <para> Модуль может быть скомбинирован с другими модулями доступа, такими как <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>, <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> и <link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link> с помощью директивы <link doc="ngx_http_core_module.xml" id="satisfy"/>. </para> <para> <note> Модуль доступен как часть <commercial_version>коммерческой подписки</commercial_version>. </note> </para> </section> <section id="algorithms" name="Поддерживаемые алгоритмы"> <para> Модуль поддерживает следующие криптографические <link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">алгоритмы</link>. </para> <para> Алгоритмы JWS: <list type="bullet"> <listitem> HS256, HS384, HS512 </listitem> <listitem> RS256, RS384, RS512 </listitem> <listitem> ES256, ES384, ES512 </listitem> <listitem> EdDSA (подписи Ed25519 и Ed448) (1.15.7) </listitem> </list> <note> До версии 1.13.7 поддерживались только алгоритмы HS256, RS256 и ES256. </note> </para> <para> Алгоритмы JWE для шифрования содержимого (1.19.7): <list type="bullet"> <listitem> A128CBC-HS256, A192CBC-HS384, A256CBC-HS512 </listitem> <listitem> A128GCM, A192GCM, A256GCM </listitem> </list> </para> <para> Алгоритмы JWE для управления ключом (1.19.9): <list type="bullet"> <listitem> A128KW, A192KW, A256KW </listitem> <listitem> A128GCMKW, A192GCMKW, A256GCMKW </listitem> <listitem> dir—прямое использование симметричного ключа в качестве ключа шифрования содержимого </listitem> <listitem> RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) </listitem> </list> </para> </section> <section id="example" name="Пример конфигурации"> <para> <example> location / { auth_jwt "closed site"; auth_jwt_key_file conf/keys.json; } </example> </para> </section> <section id="directives" name="Директивы"> <directive name="auth_jwt"> <syntax> <value>строка</value> [<literal>token=</literal><value>$переменная</value>] | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Включает проверку JSON Web Token. Заданная <value>строка</value> используется в качестве <literal>realm</literal>. В значении параметра допустимо использование переменных. </para> <para> Необязательный параметр <literal>token</literal> задаёт переменную, содержащую JSON Web Token. По умолчанию JWT передаётся в заголовке <header>Authorization</header> в качестве <link url="https://datatracker.ietf.org/doc/html/rfc6750">Bearer Token</link>. JWT может также передаваться как кука или часть строки запроса: <example> auth_jwt "closed site" token=$cookie_auth_token; </example> </para> <para> Специальное значение <literal>off</literal> отменяет действие унаследованной с предыдущего уровня конфигурации директивы <literal>auth_jwt</literal>. </para> </directive> <directive name="auth_jwt_claim_set"> <syntax><value>$переменная</value> <value>имя</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> Устанавливает <value>переменную</value> в параметр JWT claim, определяемый именами ключей. Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми. <example> auth_jwt_claim_set $email info e-mail; auth_jwt_claim_set $job info "job title"; </example> <note> До версии 1.13.7 можно было указать лишь одно имя, результат для массивов был не определён. </note> </para> <para> <note> Значения переменных для tokens, зашифрованных при помощи JWE, доступны только после дешифрования, которое происходит в <link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе. </note> </para> </directive> <directive name="auth_jwt_header_set"> <syntax><value>$переменная</value> <value>имя</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> Устанавливает <value>переменную</value> в параметр заголовка JOSE, определяемый именами ключей. Сопоставление имён начинается с верхнего уровня дерева JSON. Для массива переменная хранит список его элементов, разделяемых запятыми. <note> До версии 1.13.7 можно было указать лишь одно имя, результат для массивов был не определён. </note> </para> </directive> <directive name="auth_jwt_key_cache"> <syntax><value> время</value></syntax> <default>0</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.21.4</appeared-in> <para> Разрешает или запрещает кэширование ключей, полученных из <link id="auth_jwt_key_file">файла</link> или из <link id="auth_jwt_key_request">подзапроса</link>, и задаёт время их кэширования. Кэширование ключей, полученных из переменных, не поддерживается. По умолчанию кэширование ключей выключено. </para> </directive> <directive name="auth_jwt_key_file"> <syntax><value>файл</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Задаёт <value>файл</value> в формате <link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> для проверки подписи JWT. В значении параметра допустимо использование переменных. </para> <para> На одном уровне может быть указано несколько директив <literal>auth_jwt_key_file</literal> (1.21.1): <example> auth_jwt_key_file conf/keys.json; auth_jwt_key_file conf/key.jwk; </example> Если хотя бы один из указанных ключей не может быть загружен или обработан, nginx вернёт ошибку <http-status code="500" text="Internal Server Error"/>. </para> </directive> <directive name="auth_jwt_key_request"> <syntax><value>uri</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <appeared-in>1.15.6</appeared-in> <para> Позволяет получать файл в формате <link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> из подзапроса для проверки подписи JWT и задаёт URI, на который будет отправлен подзапрос. В значении параметра допустимо использование переменных. Для предотвращения дополнительных затрат на проверку файл рекомендутеся кэшировать. <example> 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; } } </example> На одном уровне может быть указано несколько директив <literal>auth_jwt_key_request</literal> (1.21.1): <example> auth_jwt_key_request /jwks_uri; auth_jwt_key_request /jwks2_uri; </example> Если хотя бы один из указанных ключей не может быть загружен или обработан, nginx вернёт ошибку <http-status code="500" text="Internal Server Error"/>. </para> </directive> <directive name="auth_jwt_leeway"> <syntax><value>время</value></syntax> <default>0s</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.13.10</appeared-in> <para> Задаёт максимально допустимое отклонение времени для компенсации расхождения часов при проверке JWT claims <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4">exp</link> и <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5">nbf</link>. </para> </directive> <directive name="auth_jwt_type"> <syntax><value>signed</value> | <value>encrypted</value> | <value>nested</value></syntax> <default>signed</default> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <appeared-in>1.19.7</appeared-in> <para> Задаёт ожидаемый тип JSON Web Token: JWS (<literal>signed</literal>), JWE (<literal>encrypted</literal>) или подписанный и затем зашифрованный Nested JWT (<literal>nested</literal>) (1.21.0). </para> </directive> <directive name="auth_jwt_require"> <syntax> <value>$значение</value> ... [<literal>error</literal>=<literal>401</literal> | <literal>403</literal>] </syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <appeared-in>1.21.2</appeared-in> <para> Задаёт дополнительные условия для проверки JWT. В качестве значения можно использовать текст, переменные и их комбинации, значение должно начинаться c переменной (1.21.7). Для успешной аутентификации необходимо, чтобы значение всех строковых параметров было непустое или не равно “0”. <example> map $jwt_claim_iss $valid_jwt_iss { "good" 1; } ... auth_jwt_require $valid_jwt_iss; </example> </para> <para> При невыполнении любого из условий возвращается код ответа <literal>401</literal>. Необязательный параметр <literal>error</literal> (1.21.7) позволяет переопределить код ответа на <literal>403</literal>. </para> </directive> </section> <section id="variables" name="Встроенные переменные"> <para> Модуль <literal>ngx_http_auth_jwt_module</literal> поддерживает встроенные переменные: </para> <para> <list type="tag" compact="yes"> <tag-name id="var_jwt_header_"><var>$jwt_header_</var><value>имя</value></tag-name> <tag-desc> возвращает значение указанного <link url="https://datatracker.ietf.org/doc/html/rfc7515#section-4">заголовка JOSE</link> </tag-desc> <tag-name id="var_jwt_claim_"><var>$jwt_claim_</var><value>имя</value></tag-name> <tag-desc> возвращает значение указанной <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4">JWT claim</link> <para> Для вложенных claim, а также claim, содержащих точку (“.”), значение переменной вычислить невозможно, следует использовать директиву <link id="auth_jwt_claim_set"/>. </para> <para> Значения переменных для tokens, зашифрованных при помощи JWE, доступны только после дешифрования, которое происходит в <link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе. </para> </tag-desc> <tag-name id="var_jwt_payload"><var>$jwt_payload</var></tag-name> <tag-desc> возвращает расшифрованную полезную нагрузку (payload) верхнего уровня для <literal>вложенных</literal> или <literal>зашифрованных</literal> токенов (1.21.2). Для вложенных токенов возвращает внутренний JWS токен. Для зашифрованных токенов возвращает JSON с claims. </tag-desc> </list> </para> </section> </module>