ngx_http_auth_jwt_module モジュール
Supported Algorithms 設定例 ディレクティブ auth_jwt auth_jwt_claim_set auth_jwt_header_set auth_jwt_key_cache auth_jwt_key_file auth_jwt_key_request auth_jwt_leeway auth_jwt_type auth_jwt_require 組み込み変数 |
ngx_http_auth_jwt_module
モジュール (1.11.3) は指定されたキーを使って提供された JSON Web トークン (JWT) を検証することでクライアント認証を実装します。このモジュールは、JSON Web Signature (JWS)、JSON Web Encryption (JWE) (1.19.7)、Nested JWT (1.21.0)をサポートします。モジュールはOpenID Connect 認証のために使うことができます。
モジュールは、satisfyディレクティブによってngx_http_access_module、ngx_http_auth_basic_module および ngx_http_auth_request_moduleのような他のアクセスモジュールと組み合わされるかも知れません。
このモジュールは商用許可の一部として利用可能です。
サポートされたアルゴリズム
このモジュールは以下のJSON Web アルゴリズムをサポートします。
JWS algorithms:
- HS256, HS384, HS512
- RS256, RS384, RS512
- ES256, ES384, ES512
- EdDSA (Ed25519 and Ed448 signatures) (1.15.7)
バージョン 1.13.7より前は、HS256, RS256, ES256 アルゴリズムだけがサポートされました。
JWE content encryption algorithms (1.19.7):
- A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
- A128GCM, A192GCM, A256GCM
JWE key management algorithms (1.19.9):
- A128KW, A192KW, A256KW
- A128GCMKW, A192GCMKW, A256GCMKW
- dir - direct use of a shared symmetric key as the content encryption key
- RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0)
設定例
location / { auth_jwt "closed site"; auth_jwt_key_file conf/keys.json; }
ディレクティブ
構文: |
auth_jwt
|
---|---|
デフォルト: |
auth_jwt off; |
コンテキスト: |
http , server , location , limit_except |
JSON Webトークンの検証を有効にします。指定された文字列
はrealm
として使われます。パラメータの値には変数を含めることができます。
任意のtoken
パラメータはJSON Webトークンを含む変数を指定します。デフォルトでは、JWTはBearer トークンとして "Authorization" の中に渡されます。JWT はクッキーまたはクエリ文字列の一部としても渡されるかも知れません:
auth_jwt "closed site" token=$cookie_auth_token;
特別な値 off
は上の設定レベルから受け継いだauth_jwt
ディレクティブの影響をキャンセルします。
構文: |
auth_jwt_claim_set |
---|---|
デフォルト: | - |
コンテキスト: |
http |
このディレクティブはバージョン1.11.10から導入されました。
変数
をキー名で識別されるJWT claim パラメータに設定します。名前の一致はJSON木のトップレベルから開始します。配列については、変数はカンマで区切られる配列の要素のリストを維持します。
auth_jwt_claim_set $email info e-mail; auth_jwt_claim_set $job info "job title";
バージョン 1.13.7より前は1つののキー名だけが指定することができ、結果は配列には定義されませんでした。
JWEで暗号化されたトークンの変数値は、アクセスフェーズで発生する復号化後にのみ利用できます。
構文: |
auth_jwt_header_set |
---|---|
デフォルト: | - |
コンテキスト: |
http |
このディレクティブはバージョン1.11.10から導入されました。
変数
をキー名で識別されるJOSEヘッダパラメータに設定します。名前の一致はJSON木のトップレベルから開始します。配列については、変数はカンマで区切られる配列の要素のリストを維持します。
バージョン 1.13.7より前は1つののキー名だけが指定することができ、結果は配列には定義されませんでした。
構文: |
auth_jwt_key_cache |
---|---|
デフォルト: |
auth_jwt_key_cache 0; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン1.21.4から導入されました。
fileまたはsubrequestから取得したキーのキャッシュを有効または無効にし、それらにキャッシュ時間を設定します。変数から取得されたキーのキャッシュはサポートされません。デフォルトでは、キーのキャッシュは無効です。
構文: |
auth_jwt_key_file |
---|---|
デフォルト: | - |
コンテキスト: |
http , server , location , limit_except |
JWT署名を検証するためにJSON Web Key Setの中の file
を指定します。パラメータの値には変数を含めることができます。
いくつかの auth_jwt_key_file
ディレクティブは同じレベルに指定されるかも知れません(1.21.1):
auth_jwt_key_file conf/keys.json; auth_jwt_key_file conf/key.jwk;
指定されたキーの少なくとも1つをロードまたは処理できなかった場合、nginxは500 (Internal Server Error) エラーを返します。
構文: |
auth_jwt_key_request |
---|---|
デフォルト: | - |
コンテキスト: |
http , server , location , limit_except |
このディレクティブはバージョン1.15.6から導入されました。
JWT署名を検証するためにサブリクエストからJSON Web Key Setファイルを取得できるようにし、サブリクエストの送信先のURIをせっていします。パラメータの値には変数を含めることができます。検証のオーバーヘッドを回避するには、キーファイルをキャッシュすることをお勧めします:
proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m; server { ... location / { auth_jwt "closed site"; auth_jwt_key_request /jwks_uri; } location = /jwks_uri { internal; proxy_cache foo; proxy_pass http://idp.example.com/keys; } }
いくつかの auth_jwt_key_request
ディレクティブは同じレベルに指定されるかも知れません(1.21.1):
auth_jwt_key_request /jwks_uri; auth_jwt_key_request /jwks2_uri;
指定されたキーの少なくとも1つをロードまたは処理できなかった場合、nginxは500 (Internal Server Error) エラーを返します。
構文: |
auth_jwt_leeway |
---|---|
デフォルト: |
auth_jwt_leeway 0s; |
コンテキスト: |
http , server , location |
このディレクティブはbーアジョン1.13.10で導入されました。
expおよびnbf JWT クレームを検証する時に、クロックのスキューを補償する最大許容余地を設定します。
構文: |
auth_jwt_type |
---|---|
デフォルト: |
auth_jwt_type signed; |
コンテキスト: |
http , server , location , limit_except |
このディレクティブはバージョン1.19.7から導入されました。
期待する JSON Web トークンのタイプを指定します: JWS (signed
)、JWE (encrypted
)、署名および暗号化されたNested JWT (nested
) (1.21.0)。
構文: |
auth_jwt_require
|
---|---|
デフォルト: | - |
コンテキスト: |
http , server , location , limit_except |
このディレクティブはバージョン1.21.2から導入されました。
JWT検証の追加チェックを指定します。値には、テキスト、変数、およびそれらの組み合わせを含めることができ、変数から始める必要があります (1.21.7)。認証は、全ての値が空ではなく、“0”に等しくない場合にのみ成功します。
map $jwt_claim_iss $valid_jwt_iss { "good" 1; } ... auth_jwt_require $valid_jwt_iss;
いずれかのチェックが失敗した場合、401
エラーコードが返されます。オプションのerror
パラメータ(1.21.7)を使うと、エラーコードを403
に再定義できます。
埋め込み変数
ngx_http_auth_jwt_module
モジュールは埋め込みの変数をサポートします:
$jwt_header_
name
- 指定されたJOSE ヘッダの値を返します。
$jwt_claim_
name
-
指定されたJWT claimの値を返します。
入れ子になったクレームおよびドット(“.”)を含むクレームの場合、変数の値は評価できません: 代わりにauth_jwt_claim_setディレクティブを使う必要があります。
JWEで暗号化されたトークンの変数値は、アクセスフェーズで発生する復号化後にのみ利用できます。
$jwt_payload
-
ネストされた
または暗号化された
トークンの復号化された最上位ペイロードを返します(1.21.2)。ネストされたトークンの場合、enclosed JWS トークンを返します。暗号化されたトークンの場合、クレームを含むJSONを返します。