Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_auth_jwt_module.xml @ 2968:3ba229c95e50
Linux packages: documented lack of HTTP/3 support for older distros.
author | Konstantin Pavlov <thresh@nginx.com> |
---|---|
date | Tue, 23 May 2023 14:53:59 -0700 |
parents | 8bd6f772005f |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Module ngx_http_auth_jwt_module" link="/en/docs/http/ngx_http_auth_jwt_module.html" lang="en" rev="12"> <section id="summary"> <para> The <literal>ngx_http_auth_jwt_module</literal> module (1.11.3) implements client authorization by validating the provided <link url="https://datatracker.ietf.org/doc/html/rfc7519">JSON Web Token</link> (JWT) using the specified keys. The module supports <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), and Nested JWT (1.21.0). The module can be used for <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link> authentication. </para> <para> The module may be combined with other access modules, such as <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>, and <link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>, via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive. </para> <para> <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> HS256, HS384, HS512 </listitem> <listitem> RS256, RS384, RS512 </listitem> <listitem> ES256, ES384, ES512 </listitem> <listitem> EdDSA (Ed25519 and Ed448 signatures) (1.15.7) </listitem> </list> <note> Prior to version 1.13.7, only HS256, RS256, ES256 algorithms were supported. </note> </para> <para> 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—direct use of a shared symmetric key as the content encryption key </listitem> <listitem> RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0) </listitem> </list> </para> </section> <section id="example" name="Example Configuration"> <para> <example> location / { auth_jwt "closed site"; auth_jwt_key_file conf/keys.json; } </example> </para> </section> <section id="directives" name="Directives"> <directive name="auth_jwt"> <syntax> <value>string</value> [<literal>token=</literal><value>$variable</value>] | <literal>off</literal></syntax> <default>off</default> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Enables validation of JSON Web Token. The specified <value>string</value> is used as a <literal>realm</literal>. Parameter value can contain variables. </para> <para> The optional <literal>token</literal> parameter specifies a variable that contains JSON Web Token. By default, JWT is passed in the <header>Authorization</header> header as a <link url="https://datatracker.ietf.org/doc/html/rfc6750">Bearer Token</link>. JWT may be also passed as a cookie or a part of a query string: <example> auth_jwt "closed site" token=$cookie_auth_token; </example> </para> <para> The special value <literal>off</literal> cancels the effect of the <literal>auth_jwt</literal> directive inherited from the previous configuration level. </para> </directive> <directive name="auth_jwt_claim_set"> <syntax><value>$variable</value> <value>name</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> Sets the <value>variable</value> to a JWT claim parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas. <example> auth_jwt_claim_set $email info e-mail; auth_jwt_claim_set $job info "job title"; </example> <note> Prior to version 1.13.7, only one key name could be specified, 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> <directive name="auth_jwt_header_set"> <syntax><value>$variable</value> <value>name</value> ...</syntax> <default/> <context>http</context> <appeared-in>1.11.10</appeared-in> <para> Sets the <value>variable</value> to a JOSE header parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas. <note> Prior to version 1.13.7, only one key name could be specified, and the result was undefined for arrays. </note> </para> </directive> <directive name="auth_jwt_key_cache"> <syntax><value>time</value></syntax> <default>0</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.21.4</appeared-in> <para> Enables or disables caching of keys obtained from a <link id="auth_jwt_key_file">file</link> or from a <link id="auth_jwt_key_request">subrequest</link>, and sets caching time for them. Caching of keys obtained from variables is not supported. By default, caching of keys is disabled. </para> </directive> <directive name="auth_jwt_key_file"> <syntax><value>file</value></syntax> <default/> <context>http</context> <context>server</context> <context>location</context> <context>limit_except</context> <para> Specifies a <value>file</value> in <link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> format for validating JWT signature. Parameter value can contain variables. </para> <para> Several <literal>auth_jwt_key_file</literal> directives can be specified on the same level (1.21.1): <example> auth_jwt_key_file conf/keys.json; auth_jwt_key_file conf/key.jwk; </example> If at least one of the specified keys cannot be loaded or processed, nginx will return the <http-status code="500" text="Internal Server Error"/> 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> Allows retrieving a <link url="https://datatracker.ietf.org/doc/html/rfc7517#section-5">JSON Web Key Set</link> file from a subrequest for validating JWT signature and sets the URI where the subrequest will be sent to. Parameter value can contain variables. To avoid validation overhead, it is recommended to cache the key file: <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> Several <literal>auth_jwt_key_request</literal> directives can be specified on the same level (1.21.1): <example> auth_jwt_key_request /jwks_uri; auth_jwt_key_request /jwks2_uri; </example> If at least one of the specified keys cannot be loaded or processed, nginx will return the <http-status code="500" text="Internal Server Error"/> error. </para> </directive> <directive name="auth_jwt_leeway"> <syntax><value>time</value></syntax> <default>0s</default> <context>http</context> <context>server</context> <context>location</context> <appeared-in>1.13.10</appeared-in> <para> Sets the maximum allowable leeway to compensate clock skew when verifying the <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4">exp</link> and <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5">nbf</link> JWT claims. </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> Specifies which type of JSON Web Token to expect: JWS (<literal>signed</literal>), JWE (<literal>encrypted</literal>), or signed and then encrypted Nested JWT (<literal>nested</literal>) (1.21.0). </para> </directive> <directive name="auth_jwt_require"> <syntax> <value>$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> Specifies additional checks for JWT validation. The value can contain text, variables, and their combination, and must start with a variable (1.21.7). The authentication will succeed only if all the values are not empty and are not equal to “0”. <example> map $jwt_claim_iss $valid_jwt_iss { "good" 1; } ... auth_jwt_require $valid_jwt_iss; </example> </para> <para> If any of the checks fails, the <literal>401</literal> error code is returned. The optional <literal>error</literal> parameter (1.21.7) allows redefining the error code to <literal>403</literal>. </para> </directive> </section> <section id="variables" name="Embedded Variables"> <para> The <literal>ngx_http_auth_jwt_module</literal> module supports embedded variables: </para> <para> <list type="tag" compact="yes"> <tag-name id="var_jwt_header_"><var>$jwt_header_</var><value>name</value></tag-name> <tag-desc> returns the value of a specified <link url="https://datatracker.ietf.org/doc/html/rfc7515#section-4">JOSE header</link> </tag-desc> <tag-name id="var_jwt_claim_"><var>$jwt_claim_</var><value>name</value></tag-name> <tag-desc> returns the value of a specified <link url="https://datatracker.ietf.org/doc/html/rfc7519#section-4">JWT claim</link> <para> 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> <tag-name id="var_jwt_payload"><var>$jwt_payload</var></tag-name> <tag-desc> returns the decrypted top-level payload of <literal>nested</literal> or <literal>encrypted</literal> tokens (1.21.2). For nested tokens returns the enclosed JWS token. For encrypted tokens returns JSON with claims. </tag-desc> </list> </para> </section> </module>