<?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://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT)
при помощи указанных ключей.
Модуль поддерживает
<link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS),
<link url="https://tools.ietf.org/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&mdash;прямое использование симметричного ключа
в качестве ключа шифрования содержимого
</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://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>

<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_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>

<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://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>
На одном уровне может быть указано
несколько директив <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://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>


<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> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>limit_except</context>
<appeared-in>1.21.2</appeared-in>

<para>
Задаёт дополнительные условия для проверки JWT.
В качестве значения можно использовать текст, переменные и их комбинации.
Для успешной аутентификации необходимо, чтобы
значение всех строковых параметров было непустое или не равно “0”.
<example>
map $jwt_claim_iss $valid_jwt_iss {
    "good" 1;
}
...

auth_jwt_require $valid_jwt_iss;
</example>
</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>

<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>