Mercurial > hg > nginx-site
comparison 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 |
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> |