Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_auth_jwt_module.xml @ 2688:dd2bbd104146
Unified spelling of UTF-8 in njs.
Rules for spelling UTF-8 in njs Reference:
- utf8 when it is a value
- UTF-8 when it is a part of a text
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 19 Mar 2021 18:24:34 +0000 |
parents | dd3ac7eefeed |
children | 1f2bd0d9a06c |
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="10"> <section id="summary"> <para> Модуль <literal>ngx_http_auth_jwt_module</literal> (1.11.3) предоставляет возможность авторизации клиента с проверкой предоставляемого <link url="https://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT) при помощи указанных ключей. JWT claims должны быть зашифрованы в структуре <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS). Модуль может использоваться для настройки аутентификации <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> Модуль поддерживает следующие криптографические <link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">алгоритмы</link>: <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> До версии 1.13.7 поддерживались только алгоритмы HS256, RS256 и ES256. </para> <para> <note> Модуль доступен как часть <commercial_version>коммерческой подписки</commercial_version>. </note> </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://tools.ietf.org/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> </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_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://tools.ietf.org/html/rfc7517#section-5">JSON Web Key Set</link> для проверки подписи JWT. В значении параметра допустимо использование переменных. </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://tools.ietf.org/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> </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://tools.ietf.org/html/rfc7519#section-4.1.4">exp</link> и <link url="https://tools.ietf.org/html/rfc7519#section-4.1.5">nbf</link>. </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://tools.ietf.org/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://tools.ietf.org/html/rfc7519#section-4">JWT claim</link> <para> Для вложенных claim, а также claim, содержащих точку (“.”), значение переменной вычислить невозможно, следует использовать директиву <link id="auth_jwt_claim_set"/>. </para> </tag-desc> </list> </para> </section> </module>