Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_auth_jwt_module.xml @ 2559:82e6029db0c0
Updated with Netcraft June 2020 Web Server Survey stats.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 25 Jun 2020 13:12:56 +0100 |
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="Module ngx_http_auth_jwt_module" link="/en/docs/http/ngx_http_auth_jwt_module.html" lang="en" rev="10"> <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://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT) using the specified keys. JWT claims must be encoded in a <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS) structure. 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> The module supports the following cryptographic <link url="https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms">algorithms</link>: <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> Prior to version 1.13.7, only HS256, RS256, ES256 algorithms were supported. </para> <para> <note> This module is available as part of our <commercial_version>commercial subscription</commercial_version>. </note> </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://tools.ietf.org/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> </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_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://tools.ietf.org/html/rfc7517#section-5">JSON Web Key Set</link> format for validating JWT signature. Parameter value can contain variables. </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://tools.ietf.org/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. 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> </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://tools.ietf.org/html/rfc7519#section-4.1.4">exp</link> and <link url="https://tools.ietf.org/html/rfc7519#section-4.1.5">nbf</link> JWT claims. </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://tools.ietf.org/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://tools.ietf.org/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> </tag-desc> </list> </para> </section> </module>