モジュール ngx_http_auth_jwt_module

ngx_http_auth_jwt_module モジュール (1.11.3) は、指定されたキーを使用して提供されたJSON Web Token (JWT) を検証することで、クライアント認証を実装します。このモジュールは、JSON Web Signature (JWS)、JSON Web Encryption (JWE) (1.19.7)、およびネストされた JWT (1.21.0) をサポートしています。このモジュールはOpenID Connect認証に使用できます。

このモジュールは、ngx_http_access_module、ngx_http_auth_basic_module、ngx_http_auth_request_moduleなどの他のアクセスモジュールと、satisfy ディレクティブを使用して組み合わせることができます。

このモジュールは、当社の商用サブスクリプションの一部として提供されています。

このモジュールは、以下のJSON Web アルゴリズムをサポートしています。

JWS アルゴリズム

• HS256、HS384、HS512
• RS256、RS384、RS512
• ES256、ES384、ES512
• EdDSA (Ed25519 および Ed448 署名) (1.15.7)

バージョン 1.13.7 より前は、HS256、RS256、ES256 アルゴリズムのみがサポートされていました。

JWE コンテンツ暗号化アルゴリズム (1.19.7)

• A128CBC-HS256、A192CBC-HS384、A256CBC-HS512
• A128GCM、A192GCM、A256GCM

JWE キー管理アルゴリズム (1.19.9)

• A128KW、A192KW、A256KW
• A128GCMKW、A192GCMKW、A256GCMKW
• dir - 共有対称キーをコンテンツ暗号化キーとして直接使用
• 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 off;

JSON Web Token の検証を有効にします。指定された文字列はrealmとして使用されます。パラメータ値には変数を含めることができます。

オプションのtokenパラメータは、JSON Web Token を含む変数を指定します。デフォルトでは、JWT はBearer Tokenとして「Authorization」ヘッダーで渡されます。JWT は、Cookie またはクエリ文字列の一部として渡すこともできます。

auth_jwt "closed site" token=$cookie_auth_token;

特殊値offは、前の設定レベルから継承されたauth_jwtディレクティブの効果をキャンセルします。

キー名で識別される JWT クレームパラメータを変数に設定します。名前の一致はJSONツリーの最上位レベルから開始されます。配列の場合、変数はコンマで区切られた配列要素のリストを保持します。

auth_jwt_claim_set $email info e-mail;
auth_jwt_claim_set $job info "job title";

バージョン 1.13.7 より前は、キー名を1つしか指定できず、配列の結果は未定義でした。

JWEで暗号化されたトークンの変数値は、アクセスフェーズで発生する復号化後にのみ使用できます。

キー名で識別される JOSE ヘッダーパラメータを変数に設定します。名前の一致はJSONツリーの最上位レベルから開始されます。配列の場合、変数はコンマで区切られた配列要素のリストを保持します。

バージョン 1.13.7 より前は、キー名を1つしか指定できず、配列の結果は未定義でした。

auth_jwt_key_cache 0;

ファイルまたはサブリクエストから取得したキーのキャッシングを有効または無効にし、それらのキャッシング時間を設定します。変数から取得したキーのキャッシングはサポートされていません。デフォルトでは、キーのキャッシングは無効になっています。

JWT 署名の検証のためのJSON Web Key Set形式のファイルを指定します。パラメータ値には変数を含めることができます。

同じレベルに複数のauth_jwt_key_fileディレクティブを指定できます (1.21.1)

auth_jwt_key_file conf/keys.json;
auth_jwt_key_file conf/key.jwk;

指定されたキーの少なくとも1つを読み込めなかったり、処理できなかった場合、nginx は500（内部サーバーエラー）エラーを返します。

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（内部サーバーエラー）エラーを返します。

auth_jwt_leeway 0s;

expおよびnbf JWTクレームを検証する際のクロックスキューを補償するための最大許容範囲を設定します。

auth_jwt_type signed;

期待するJSON Web Tokenの種類を指定します：JWS (signed)、JWE (encrypted)、または署名してから暗号化されたネストされたJWT (nested) (1.21.0)。

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_名前

指定されたJOSEヘッダーの値を返します。

$jwt_claim_名前

指定されたJWTクレームの値を返します。

ネストされたクレームやドット（「.」）を含むクレームの場合、変数の値を評価することはできません。auth_jwt_claim_setディレクティブを使用する必要があります。

JWEで暗号化されたトークンの変数値は、アクセスフェーズで発生する復号化後にのみ使用できます。

$jwt_payload

nestedまたはencryptedトークンの復号化された最上位レベルのペイロードを返します (1.21.2)。ネストされたトークンの場合は、囲まれたJWSトークンを返します。暗号化されたトークンの場合は、クレームを含むJSONを返します。