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 驗證。

此模組可以透過 satisfy 指令，與其他存取模組結合使用，例如 ngx_http_access_module、ngx_http_auth_basic_module 和 ngx_http_auth_request_module。

此模組作為我們商業訂閱的一部分提供。

此模組支援下列 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 在「Authorization」標頭中以 Bearer Token 的形式傳遞。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 版本之前，只能指定一個金鑰名稱，且陣列的結果未定義。

使用 JWE 加密的權杖變數值僅在解密後才可用，解密發生在 存取階段期間。

將 變數 設定為由金鑰名稱識別的 JOSE 標頭參數。名稱比對從 JSON 樹的頂層開始。對於陣列，變數會保留由逗號分隔的陣列元素清單。

在 1.13.7 版本之前，只能指定一個金鑰名稱，且陣列的結果未定義。

auth_jwt_key_cache 0;

啟用或停用從檔案或從子請求取得的金鑰快取，並設定它們的快取時間。不支援從變數取得的金鑰快取。依預設，會停用金鑰快取。

以 JSON Web Key Set 格式指定用於驗證 JWT 簽章的 檔案。參數值可以包含變數。

可以在同一層級上指定多個 auth_jwt_key_file 指令 (1.21.1)

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

如果至少有一個指定的金鑰無法載入或處理，nginx 將傳回 500 (內部伺服器錯誤) 錯誤。

允許從子請求擷取 JSON Web Key Set 檔案以驗證 JWT 簽章，並設定子請求將傳送到的 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;

如果至少有一個指定的金鑰無法載入或處理，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。