<?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="6">

<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://tools.ietf.org/html/rfc7518#section-3.1">algorithms</link>:

<list type="bullet">

<listitem>
HS256, HS384, HS512
</listitem>

<listitem>
RS256, RS384, RS512
</listitem>

<listitem>
ES256, ES384, ES512
</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_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_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>
location / {
    auth_jwt           "closed site";
    auth_jwt_key_file  conf/keys.json;
    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_leeway">
<syntax><value>time</value></syntax>
<default>0s</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.13.11</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>


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

</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>
</tag-desc>

</list>
</para>

</section>

</module>