Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_auth_jwt_module.xml @ 1763:a7974b8d2a23
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Mon, 22 Aug 2016 14:20:57 +0300 |
parents | |
children | b5e416ace4bf |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_auth_jwt_module.xml @@ -0,0 +1,207 @@ +<?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="1"> + +<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> +<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> [<value>token=$variable</value>] | +<literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</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> argument 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_key_file"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</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> +Variables that return +<link url="https://tools.ietf.org/html/rfc7519#section-4">JWT claims</link>: + +<list type="tag" compact="no"> +<tag-name id="var_jwt_claim_aud"><var>$jwt_claim_aud</var></tag-name> +<tag-desc> +the <literal>aud</literal> (audience) claim +</tag-desc> + +<tag-name id="var_jwt_claim_email"><var>$jwt_claim_email</var></tag-name> +<tag-desc> +the <literal>email</literal> claim +</tag-desc> + +<tag-name id="var_jwt_claim_exp"><var>$jwt_claim_exp</var></tag-name> +<tag-desc> +the <literal>exp</literal> (expiration time) claim +</tag-desc> + +<tag-name id="var_jwt_claim_iat"><var>$jwt_claim_iat</var></tag-name> +<tag-desc> +the <literal>iat</literal> (issued at) claim +</tag-desc> + +<tag-name id="var_jwt_claim_iss"><var>$jwt_claim_iss</var></tag-name> +<tag-desc> +the issuer of the claim +</tag-desc> + +<tag-name id="var_jwt_claim_jti"><var>$jwt_claim_jti</var></tag-name> +<tag-desc> +the JWT ID +</tag-desc> + +<tag-name id="var_jwt_claim_nbf"><var>$jwt_claim_nbf</var></tag-name> +<tag-desc> +the <literal>nbf</literal> (not-before time) claim +</tag-desc> + +<tag-name id="var_jwt_claim_sub"><var>$jwt_claim_sub</var></tag-name> +<tag-desc> +the subject of the JWT +</tag-desc> +</list> +</para> + +<para> +Variables that return parameters of +<link url="https://tools.ietf.org/html/rfc7515#section-4">JOSE header</link>: + +<list type="tag" compact="no"> +<tag-name id="var_jwt_header_alg"><var>$jwt_header_alg</var></tag-name> +<tag-desc> +the <literal>alg</literal> (algorithm) header parameter +</tag-desc> + +<tag-name id="var_jwt_header_cty"><var>$jwt_header_cty</var></tag-name> +<tag-desc> +the <literal>cty</literal> (content type) header parameter +</tag-desc> + +<tag-name id="var_jwt_header_enc"><var>$jwt_header_enc</var></tag-name> +<tag-desc> +the <literal>enc</literal> (encryption algorithm) header parameter +</tag-desc> + +<tag-name id="var_jwt_header_kid"><var>$jwt_header_kid</var></tag-name> +<tag-desc> +the <literal>kid</literal> (key ID) header parameter +</tag-desc> + +<tag-name id="var_jwt_header_typ"><var>$jwt_header_typ</var></tag-name> +<tag-desc> +the <literal>typ</literal> (type) header parameter +</tag-desc> + +</list> +</para> + +</section> + +</module>