Mercurial > hg > nginx-site

changeset 2713:efb3d27dfa23

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Mon, 26 Apr 2021 12:52:35 +0100
parents caa04d53b7af
children 077508e4ed7a
files xml/en/docs/http/ngx_http_auth_jwt_module.xml xml/en/docs/http/ngx_http_upstream_hc_module.xml xml/ru/docs/http/ngx_http_auth_jwt_module.xml xml/ru/docs/http/ngx_http_upstream_hc_module.xml
diffstat 4 files changed, 191 insertions(+), 17 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_auth_jwt_module.xml
+++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml
@@ -18,9 +18,11 @@ The <literal>ngx_http_auth_jwt_module</l
 implements client authorization by validating the provided
 <link url="https://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT)
 using the specified keys.
-JWT claims must be encoded in a
+JWT claims can be encoded in a
 <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS)
-structure.
+or
+<link url="https://tools.ietf.org/html/rfc7516">JSON Web Encryption</link> (JWE)
+(1.19.7) structure.
 The module can be used for
 <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>
 authentication.
@@ -37,9 +39,24 @@ via the <link doc="ngx_http_core_module.
 </para>
 
 <para>
-The module supports the following cryptographic
-<link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">algorithms</link>:
+<note>
+This module is available as part of our
+<commercial_version>commercial subscription</commercial_version>.
+</note>
+</para>
+
+</section>
+
 
+<section id="algorithms" name="Supported Algorithms">
+
+<para>
+The module supports the following JSON Web
+<link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">Algorithms</link>.
+</para>
+
+<para>
+JWS algorithms:
 <list type="bullet">
 
 <listitem>
@@ -60,15 +77,44 @@ EdDSA (Ed25519 and Ed448 signatures) (1.
 
 </list>
 
+<note>
 Prior to version 1.13.7,
 only HS256, RS256, ES256 algorithms were supported.
+</note>
 </para>
 
 <para>
-<note>
-This module is available as part of our
-<commercial_version>commercial subscription</commercial_version>.
-</note>
+JWE content encryption algorithms (1.19.7):
+<list type="bullet">
+
+<listitem>
+A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
+</listitem>
+
+<listitem>
+A128GCM, A192GCM, A256GCM
+</listitem>
+
+</list>
+</para>
+
+<para>
+JWE key management algorithms (1.19.9):
+<list type="bullet">
+
+<listitem>
+A128KW, A192KW, A256KW
+</listitem>
+
+<listitem>
+A128GCMKW, A192GCMKW, A256GCMKW
+</listitem>
+
+<listitem>
+dir&mdash;direct use of a shared symmetric key as the content encryption key
+</listitem>
+
+</list>
 </para>
 
 </section>
@@ -149,6 +195,14 @@ and the result was undefined for arrays.
 </note>
 </para>
 
+<para>
+<note>
+Variable values for tokens encrypted with JWE
+are available only after decryption which occurs during the
+<link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase.
+</note>
+</para>
+
 </directive>
 
 
@@ -249,6 +303,24 @@ JWT claims.
 
 </directive>
 
+
+<directive name="auth_jwt_type">
+<syntax><value>signed</value> | <value>encrypted</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>
+Specifies which type of JSON Web Token to expect:
+JWS (<literal>signed</literal>) or
+JWE (<literal>encrypted</literal>).
+</para>
+
+</directive>
+
 </section>
 
 
@@ -277,6 +349,12 @@ For nested claims and claims including a dot (“.”),
 the value of the variable cannot be evaluated;
 the <link id="auth_jwt_claim_set"/> directive should be used instead.
 </para>
+
+<para>
+Variable values for tokens encrypted with JWE
+are available only after decryption which occurs during the
+<link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase.
+</para>
 </tag-desc>
 
 </list>
--- a/xml/en/docs/http/ngx_http_upstream_hc_module.xml
+++ b/xml/en/docs/http/ngx_http_upstream_hc_module.xml
@@ -172,14 +172,23 @@ by default, “<literal>/</literal>”.
 </tag-desc>
 
 <tag-name id="health_check_mandatory">
-<literal>mandatory</literal>
+<literal>mandatory</literal> [<literal>persistent</literal>]
 </tag-name>
 <tag-desc>
+<para>
 sets the initial “checking” state for a server
 until the first health check is completed (1.11.7).
 Client requests are not passed to servers in the “checking” state.
 If the parameter is not specified,
 the server will be initially considered healthy.
+</para>
+
+<para id="health_check_persistent">
+The <literal>persistent</literal> parameter (1.19.7)
+sets the initial “up” state for a server after reload
+if the server was considered healthy before reload.
+</para>
+
 </tag-desc>
 
 <tag-name id="health_check_match">
--- a/xml/ru/docs/http/ngx_http_auth_jwt_module.xml
+++ b/xml/ru/docs/http/ngx_http_auth_jwt_module.xml
@@ -18,8 +18,11 @@
 предоставляет возможность авторизации клиента с проверкой предоставляемого
 <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).
+JWT claims могут быть зашифрованы в структуре
+<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).
 Модуль может использоваться для настройки аутентификации
 <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>.
 </para>
@@ -35,9 +38,24 @@ JWT claims должны быть зашифрованы в структуре
 </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>:
+<link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">алгоритмы</link>.
+</para>
 
+<para>
+Алгоритмы JWS:
 <list type="bullet">
 
 <listitem>
@@ -58,15 +76,45 @@ EdDSA (подписи Ed25519 и Ed448) (1.15.7)
 
 </list>
 
+<note>
 До версии 1.13.7
 поддерживались только алгоритмы HS256, RS256 и ES256.
+</note>
 </para>
 
 <para>
-<note>
-Модуль доступен как часть
-<commercial_version>коммерческой подписки</commercial_version>.
-</note>
+Алгоритмы 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.7):
+<list type="bullet">
+
+<listitem>
+A128KW, A192KW, A256KW
+</listitem>
+
+<listitem>
+A128GCMKW, A192GCMKW, A256GCMKW
+</listitem>
+
+<listitem>
+dir&mdash;прямое использование симметричного ключа
+в качестве ключа шифрования содержимого
+</listitem>
+
+</list>
 </para>
 
 </section>
@@ -147,6 +195,14 @@ auth_jwt_claim_set $job info "job title"
 </note>
 </para>
 
+<para>
+<note>
+Значения переменных для tokens, зашифрованных при помощи JWE,
+доступны только после дешифрования, которое происходит в
+<link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе.
+</note>
+</para>
+
 </directive>
 
 
@@ -246,6 +302,23 @@ server {
 
 </directive>
 
+<directive name="auth_jwt_type">
+<syntax><value>signed</value> | <value>encrypted</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>).
+</para>
+
+</directive>
+
 </section>
 
 
@@ -274,6 +347,12 @@ server {
 значение переменной вычислить невозможно,
 следует использовать директиву <link id="auth_jwt_claim_set"/>.
 </para>
+
+<para>
+Значения переменных для tokens, зашифрованных при помощи JWE,
+доступны только после дешифрования, которое происходит в
+<link doc="../dev/development_guide.xml" id="http_phases">Access</link>-фазе.
+</para>
 </tag-desc>
 
 </list>
--- a/xml/ru/docs/http/ngx_http_upstream_hc_module.xml
+++ b/xml/ru/docs/http/ngx_http_upstream_hc_module.xml
@@ -172,14 +172,22 @@ http {
 </tag-desc>
 
 <tag-name id="health_check_mandatory">
-<literal>mandatory</literal>
+<literal>mandatory</literal> [<literal>persistent</literal>]
 </tag-name>
 <tag-desc>
+<para>
 устанавливает исходное состояние “checking” для сервера
 до завершения первой проверки работоспособности (1.11.7).
 На серверы в состоянии “checking” клиентские запросы передаваться не будут.
 Если параметр не указан,
 то исходно сервер будет считаться работоспособным.
+</para>
+
+<para id="health_check_persistent">
+Параметр <literal>persistent</literal> (1.19.7)
+устанавливает исходное состояние “up” для сервера после перезагрузки nginx
+в случае, если до перезагрузки сервер считался работоспособным.
+</para>
 </tag-desc>
 
 <tag-name id="health_check_match">