Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_auth_jwt_module.xml @ 1763:a7974b8d2a23

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 Ruslan Ermilov <ru@nginx.com>
date Mon, 22 Aug 2016 14:20:57 +0300
parents
children b5e416ace4bf
comparison
equal deleted inserted replaced
1762:3064cb25e29d 1763:a7974b8d2a23
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_http_auth_jwt_module"
10 link="/en/docs/http/ngx_http_auth_jwt_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_http_auth_jwt_module</literal> module (1.11.3)
18 implements client authorization by validating the provided
19 <link url="https://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT)
20 using the specified keys.
21 JWT claims must be encoded in a
22 <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS)
23 structure.
24 The module can be used for
25 <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>
26 authentication.
27 </para>
28
29 <para>
30 The module may be combined with
31 other access modules, such as
32 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link>,
33 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>,
34 and
35 <link doc="ngx_http_auth_request_module.xml">ngx_http_auth_request_module</link>,
36 via the <link doc="ngx_http_core_module.xml" id="satisfy"/> directive.
37 </para>
38
39 <para>
40 <note>
41 This module is available as part of our
42 <commercial_version>commercial subscription</commercial_version>.
43 </note>
44 </para>
45
46 </section>
47
48
49 <section id="example" name="Example Configuration">
50
51 <para>
52 <example>
53 location / {
54 auth_jwt "closed site";
55 auth_jwt_key_file conf/keys.json;
56 }
57 </example>
58 </para>
59
60 </section>
61
62
63 <section id="directives" name="Directives">
64
65 <directive name="auth_jwt">
66 <syntax><value>string</value> [<value>token=$variable</value>] |
67 <literal>off</literal></syntax>
68 <default>off</default>
69 <context>http</context>
70 <context>server</context>
71 <context>location</context>
72
73 <para>
74 Enables validation of JSON Web Token.
75 The specified <value>string</value> is used as a <literal>realm</literal>.
76 Parameter value can contain variables.
77 </para>
78
79 <para>
80 The optional <literal>token</literal> argument specifies a variable
81 that contains JSON Web Token.
82 By default, JWT is passed in the <header>Authorization</header> header
83 as a
84 <link url="https://tools.ietf.org/html/rfc6750">Bearer Token</link>.
85 JWT may be also passed as a cookie or a part of a query string:
86 <example>
87 auth_jwt "closed site" token=$cookie_auth_token;
88 </example>
89 </para>
90
91 <para>
92 The special value <literal>off</literal> cancels the effect
93 of the <literal>auth_jwt</literal> directive
94 inherited from the previous configuration level.
95 </para>
96
97 </directive>
98
99
100 <directive name="auth_jwt_key_file">
101 <syntax><value>file</value></syntax>
102 <default/>
103 <context>http</context>
104 <context>server</context>
105 <context>location</context>
106
107 <para>
108 Specifies a <value>file</value> in
109 <link url="https://tools.ietf.org/html/rfc7517#section-5">JSON Web Key Set</link>
110 format for validating JWT signature.
111 Parameter value can contain variables.
112 </para>
113
114 </directive>
115
116 </section>
117
118 <section id="variables" name="Embedded Variables">
119
120 <para>
121 The <literal>ngx_http_auth_jwt_module</literal> module
122 supports embedded variables.
123 </para>
124
125 <para>
126 Variables that return
127 <link url="https://tools.ietf.org/html/rfc7519#section-4">JWT claims</link>:
128
129 <list type="tag" compact="no">
130 <tag-name id="var_jwt_claim_aud"><var>$jwt_claim_aud</var></tag-name>
131 <tag-desc>
132 the <literal>aud</literal> (audience) claim
133 </tag-desc>
134
135 <tag-name id="var_jwt_claim_email"><var>$jwt_claim_email</var></tag-name>
136 <tag-desc>
137 the <literal>email</literal> claim
138 </tag-desc>
139
140 <tag-name id="var_jwt_claim_exp"><var>$jwt_claim_exp</var></tag-name>
141 <tag-desc>
142 the <literal>exp</literal> (expiration time) claim
143 </tag-desc>
144
145 <tag-name id="var_jwt_claim_iat"><var>$jwt_claim_iat</var></tag-name>
146 <tag-desc>
147 the <literal>iat</literal> (issued at) claim
148 </tag-desc>
149
150 <tag-name id="var_jwt_claim_iss"><var>$jwt_claim_iss</var></tag-name>
151 <tag-desc>
152 the issuer of the claim
153 </tag-desc>
154
155 <tag-name id="var_jwt_claim_jti"><var>$jwt_claim_jti</var></tag-name>
156 <tag-desc>
157 the JWT ID
158 </tag-desc>
159
160 <tag-name id="var_jwt_claim_nbf"><var>$jwt_claim_nbf</var></tag-name>
161 <tag-desc>
162 the <literal>nbf</literal> (not-before time) claim
163 </tag-desc>
164
165 <tag-name id="var_jwt_claim_sub"><var>$jwt_claim_sub</var></tag-name>
166 <tag-desc>
167 the subject of the JWT
168 </tag-desc>
169 </list>
170 </para>
171
172 <para>
173 Variables that return parameters of
174 <link url="https://tools.ietf.org/html/rfc7515#section-4">JOSE header</link>:
175
176 <list type="tag" compact="no">
177 <tag-name id="var_jwt_header_alg"><var>$jwt_header_alg</var></tag-name>
178 <tag-desc>
179 the <literal>alg</literal> (algorithm) header parameter
180 </tag-desc>
181
182 <tag-name id="var_jwt_header_cty"><var>$jwt_header_cty</var></tag-name>
183 <tag-desc>
184 the <literal>cty</literal> (content type) header parameter
185 </tag-desc>
186
187 <tag-name id="var_jwt_header_enc"><var>$jwt_header_enc</var></tag-name>
188 <tag-desc>
189 the <literal>enc</literal> (encryption algorithm) header parameter
190 </tag-desc>
191
192 <tag-name id="var_jwt_header_kid"><var>$jwt_header_kid</var></tag-name>
193 <tag-desc>
194 the <literal>kid</literal> (key ID) header parameter
195 </tag-desc>
196
197 <tag-name id="var_jwt_header_typ"><var>$jwt_header_typ</var></tag-name>
198 <tag-desc>
199 the <literal>typ</literal> (type) header parameter
200 </tag-desc>
201
202 </list>
203 </para>
204
205 </section>
206
207 </module>