Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_auth_jwt_module.xml @ 2768:9dd8c203a54a

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 Yaroslav Zhuravlev <yar@nginx.com>
date Wed, 22 Sep 2021 13:47:23 +0300
parents efb3d27dfa23
children 4add6ae1296f
comparison
equal deleted inserted replaced
2767:c56adb7148a4 2768:9dd8c203a54a
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Module ngx_http_auth_jwt_module" 9 <module name="Module ngx_http_auth_jwt_module"
10 link="/en/docs/http/ngx_http_auth_jwt_module.html" 10 link="/en/docs/http/ngx_http_auth_jwt_module.html"
11 lang="en" 11 lang="en"
12 rev="11"> 12 rev="12">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 The <literal>ngx_http_auth_jwt_module</literal> module (1.11.3) 17 The <literal>ngx_http_auth_jwt_module</literal> module (1.11.3)
18 implements client authorization by validating the provided 18 implements client authorization by validating the provided
19 <link url="https://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT) 19 <link url="https://tools.ietf.org/html/rfc7519">JSON Web Token</link> (JWT)
20 using the specified keys. 20 using the specified keys.
21 JWT claims can be encoded in a 21 The module supports
22 <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS) 22 <link url="https://tools.ietf.org/html/rfc7515">JSON Web Signature</link> (JWS),
23 or
24 <link url="https://tools.ietf.org/html/rfc7516">JSON Web Encryption</link> (JWE) 23 <link url="https://tools.ietf.org/html/rfc7516">JSON Web Encryption</link> (JWE)
25 (1.19.7) structure. 24 (1.19.7), and Nested JWT (1.21.0).
26 The module can be used for 25 The module can be used for
27 <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link> 26 <link url="http://openid.net/specs/openid-connect-core-1_0.html">OpenID Connect</link>
28 authentication. 27 authentication.
29 </para> 28 </para>
30 29
110 A128GCMKW, A192GCMKW, A256GCMKW 109 A128GCMKW, A192GCMKW, A256GCMKW
111 </listitem> 110 </listitem>
112 111
113 <listitem> 112 <listitem>
114 dir&mdash;direct use of a shared symmetric key as the content encryption key 113 dir&mdash;direct use of a shared symmetric key as the content encryption key
114 </listitem>
115
116 <listitem>
117 RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0)
115 </listitem> 118 </listitem>
116 119
117 </list> 120 </list>
118 </para> 121 </para>
119 122
239 <link url="https://tools.ietf.org/html/rfc7517#section-5">JSON Web Key Set</link> 242 <link url="https://tools.ietf.org/html/rfc7517#section-5">JSON Web Key Set</link>
240 format for validating JWT signature. 243 format for validating JWT signature.
241 Parameter value can contain variables. 244 Parameter value can contain variables.
242 </para> 245 </para>
243 246
247 <para>
248 Several <literal>auth_jwt_key_file</literal> directives
249 can be specified on the same level (1.21.1):
250 <example>
251 auth_jwt_key_file conf/keys.json;
252 auth_jwt_key_file conf/key.jwk;
253 </example>
254 If at least one of the specified keys cannot be loaded or processed,
255 nginx will return the
256 <http-status code="500" text="Internal Server Error"/> error.
257 </para>
258
244 </directive> 259 </directive>
245 260
246 261
247 <directive name="auth_jwt_key_request"> 262 <directive name="auth_jwt_key_request">
248 <syntax><value>uri</value></syntax> 263 <syntax><value>uri</value></syntax>
277 proxy_cache foo; 292 proxy_cache foo;
278 proxy_pass http://idp.example.com/keys; 293 proxy_pass http://idp.example.com/keys;
279 } 294 }
280 } 295 }
281 </example> 296 </example>
297 Several <literal>auth_jwt_key_request</literal> directives
298 can be specified on the same level (1.21.1):
299 <example>
300 auth_jwt_key_request /jwks_uri;
301 auth_jwt_key_request /jwks2_uri;
302 </example>
303 If at least one of the specified keys cannot be loaded or processed,
304 nginx will return the
305 <http-status code="500" text="Internal Server Error"/> error.
282 </para> 306 </para>
283 307
284 </directive> 308 </directive>
285 309
286 310
303 327
304 </directive> 328 </directive>
305 329
306 330
307 <directive name="auth_jwt_type"> 331 <directive name="auth_jwt_type">
308 <syntax><value>signed</value> | <value>encrypted</value></syntax> 332 <syntax><value>signed</value> |
333 <value>encrypted</value> |
334 <value>nested</value></syntax>
309 <default>signed</default> 335 <default>signed</default>
310 <context>http</context> 336 <context>http</context>
311 <context>server</context> 337 <context>server</context>
312 <context>location</context> 338 <context>location</context>
313 <context>limit_except</context> 339 <context>limit_except</context>
314 <appeared-in>1.19.7</appeared-in> 340 <appeared-in>1.19.7</appeared-in>
315 341
316 <para> 342 <para>
317 Specifies which type of JSON Web Token to expect: 343 Specifies which type of JSON Web Token to expect:
318 JWS (<literal>signed</literal>) or 344 JWS (<literal>signed</literal>),
319 JWE (<literal>encrypted</literal>). 345 JWE (<literal>encrypted</literal>),
346 or signed and then encrypted
347 Nested JWT (<literal>nested</literal>) (1.21.0).
348 </para>
349
350 </directive>
351
352
353 <directive name="auth_jwt_require">
354 <syntax><value>value</value> ...</syntax>
355 <default/>
356 <context>http</context>
357 <context>server</context>
358 <context>location</context>
359 <context>limit_except</context>
360 <appeared-in>1.21.2</appeared-in>
361
362 <para>
363 Defines additional conditions for JWT validation.
364 The value can contain text, variables, and their combination.
365 The authentication will succeed only
366 if all the values are not empty and are not equal to “0”.
367 <example>
368 map $jwt_claim_iss $valid_jwt_iss {
369 "good" 1;
370 }
371 ...
372
373 auth_jwt_require $valid_jwt_iss;
374 </example>
320 </para> 375 </para>
321 376
322 </directive> 377 </directive>
323 378
324 </section> 379 </section>
355 are available only after decryption which occurs during the 410 are available only after decryption which occurs during the
356 <link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase. 411 <link doc="../dev/development_guide.xml" id="http_phases">Access</link> phase.
357 </para> 412 </para>
358 </tag-desc> 413 </tag-desc>
359 414
415 <tag-name id="var_jwt_payload"><var>$jwt_payload</var></tag-name>
416 <tag-desc>
417 returns the decrypted top-level payload
418 of <literal>nested</literal>
419 or <literal>encrypted</literal> tokens (1.21.2).
420 For nested tokens returns the enclosed JWS token.
421 For encrypted tokens returns JSON with claims.
422 </tag-desc>
423
360 </list> 424 </list>
361 </para> 425 </para>
362 426
363 </section> 427 </section>
364 428